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Chapter 1. Quick Pico Setup 


If you are developing for Raspberry Pi Pico on the Raspberry Pi 4B, or the Raspberry Pi 400, most of the installation 
steps in this Getting Started guide can be skipped by running the setup script. 


@ NOTE 


This setup script requires approximately 2.5GB of disk space on your SD card, so make sure you have enough free 


space before running it. You can check how much free disk space you have with the df -h command. 


You can get this script by running the following command in a terminal: 


$ wget https://raw.githubusercontent.com/raspberrypi/pico-setup/master/pico_setup.sh © 


1. You should first sudo apt install wget if you don't have wget already installed. 


Then make the script executable with, 


$ chmod +x pico. setup.sh 


and run it with, 


$ ./pico_setup.sh 


The script will: 
* Create a directory called pico 
* Install required dependencies 
* Download the pico-sdk, pico-examples, pico-extras, and pico-playground repositories 
* Define PICO SDK PATH, PICO EXAMPLES PATH, PICO, EXTRAS. PATH, and PICO PLAYGROUND PATH in your ^/.bashrc 
* Build the blink and hello world examples in pico-examples/build/blink and pico-examples/build/hello world 
* Download and build picotool (see Appendix B), and copy it to /usr/local/bin. 
* Download and build picoprobe (see Appendix A). 
* Download and compile OpenOCD (for debug support) 
* Download and install Visual Studio Code 
* Install the required Visual Studio Code extensions (see Chapter 7 for more details) 


* Configure the Raspberry Pi UART for use with Raspberry Pi Pico 
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@ NOTE 


The pico directory will be created in the folder where you run the pico_setup.sh script. 


Once it has run, you will need to reboot your Raspberry Pi, 
$ sudo reboot 


for the UART reconfiguration to take effect. Once your Raspberry Pi has rebooted you can open Visual Studio Code in 
the "Programming" menu and follow the instructions from Section 7.2. 
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Chapter 2. The SDK 


@ IMPORTANT 


The following instructions assume that you are using a Raspberry Pi Pico and some details may differ if you are 


using a different RP2040-based board. They also assume you are using Raspberry Pi OS running on a Raspberry Pi 4, 
or an equivalent Debian-based Linux distribution running on another platform. Alternative instructions for those 
using Microsoft Windows (see Section 9.2) or Apple macOS (see Section 9.1) are also provided. 


The Raspberry Pi Pico is built around the RP2040 microcontroller designed by Raspberry Pi. Development on the board 
is fully supported with both a C/C++ SDK, and an official MicroPython port. This book talks about how to get started 
with the SDK, and walks you through how to build, install, and work with the SDK toolchain. 


@ TIP 


For more information on the official MicroPython port see the Raspberry Pi Pico Python SDK book which documents 
the port, and Get started with MicroPython on Raspberry Pi Pico by Gareth Halfacree and Ben Everard, published by 
Raspberry Pi Press. 


@ TIP 


For more information on the C/C++ SDK, along with API-level documentation, see the Raspberry Pi Pico C/C++ SDK 


book. 


2.1. Get the SDK and examples 


The Pico Examples repository provides a set of example applications that are written using the SDK. To clone these 
repositories start by creating a pico directory to keep all pico related checkouts in. These instructions create a pico 
directory at /home/pi/pico. 


$ cd 
$ mkdir pico 
$ cd pico 


Then clone the pico-sdk and pico-examples git repositories. 


$ git clone https://github.com/raspberrypi/pico-sdk.git --branch master 

$ cd pico-sdk 

$ git submodule update --init 

S ca 2- 

$ git clone https://github.com/raspberrypi/pico-examples.git --branch master 
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Q WARNING 


Failure to run the git submodule update --init command above will mean that the tinyusb module will not be included, 


and as a result USB functionality will not be compiled into the SDK. This means that USB serial, other USB functions, 
and example code will not work. 


@ NOTE 


There are additional repositories: Pico Extras, and Pico Playground that you may also be interested in. 


2.2. Install the Toolchain 


To build the applications in pico-examples, you'll need to install some extra tools. To build projects you'll need CMake, a 
cross-platform tool used to build the software, and the GNU Embedded Toolchain for Arm. You can install both of these 
via apt from the command line. Anything you already have installed will be ignored by apt. 


$ sudo apt update 
$ sudo apt install cmake gcc-arm-none-eabi libnewlib-arm-none-eabi build-essential © 


1. Native gcc and g++ are needed to compile pioasm and elf2uf2. 


@ NOTE 


Ubuntu and Debian users might additionally need to also install Libstdc++-arm-none-eabi-newlib. 


2.3. Updating the SDK 


When a new version of the SDK is released you will need to update your copy of the SDK. To do this go into the pico-sdk 
directory which contains your copy of the SDK, and do the following; 


$ cd pico-sdk 
$ git pull 
$ git submodule update 


@ NOTE 


If you wish to be informed of new releases you can get notified by setting up a custom watch on the pico-sdk 


repository. Navigate to https://github.com/raspberrypi/pico-sdk and then select Watch > Custom > Releases. You 
will receive an email notification every time there is a new SDK release. 
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Chapter 3. Blinking an LED in C 


When you're writing software for hardware, turning an LED on, off, and then on again, is typically the first program that 
gets run in a new programming environment. Learning how to blink an LED gets you half way to anywhere. 


So let's go ahead blink the LED on the Raspberry Pi Pico. 


This example uses the following code for the Raspberry Pi Pico, blinking the LED connected to pin 25 of the RP2040: 


Pico Examples: https://github.com/raspberrypi/pico-examples/blob/master/blink/blink.c Lines 9 - 23 


9 int main() ( 
10 #ifndef PICO DEFAULT. LED PIN 
11 #warning blink example requires a board with a regular LED 


12 #else 

13 const uint LED. PIN = PICO. DEFAULT. LED. PIN; 
14 gpro init(LED. PIN); 

15) gpio_set_dir(LED_PIN, GPIO. OUT); 
16 while (true) ( 

lz gpio_put(LED_PIN, 1); 

18 sleep. ms(250); 

19 gpio.put(LED. PIN, 0); 

20 sleep. ms(250); 

21 } 

22 #endif 

23 } 


And the following alternate code for the Raspberry Pi Pico W, which blinks the LED connected to the Infineon 43439 
wireless chip with WL GPIO0: 


Pico Examples: https://github.com/raspberrypi/pico-examples/blob/master/pico_w/wifi/blink/picow_blink.c Lines 10 - 22 


10 int main() { 


11 stdio_init_all(); 

12 if (cyw43_arch_init()) { 

13 printf("Wi-Fi init failed") ; 

14 return -1; 

15 } 

16 while (true) { 

17 cyw43. arch. gpio. put(CYWA43. WL. GPIO. LED. PIN, 1); 
18 sleep. ms(250); 

19 cyw43. arch. gpio. put(CYWA43. WL. GPIO LED. PIN, 0); 
20 sleep. ms(250); 

21 } 

22) 


3.1. Building "Blink" 


From the pico directory we created earlier, navigate into pico-examples and create a build directory: 


$ cd pico-examples 
$ mkdir build 
$ cd build 
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Then set the PICO SDK PATH, assuming you cloned the pico-sdk and pico-examples repositories into the same directory: 


$ export PICO. SDK PATH-../../pico-sdk 


@ TIP 


Throughout this book we use the relative path ../../pico-sdk to the SDK repository for PICO_SDK_PATH. Depending on 


the location of your repository, you could replace this with an absolute path. 


3.1.1. Build "Blink" for the Pico 


Prepare your cmake build directory by running the following command: 


$ cmake .. 
Using PICO.SDK. PATH from environment ('../../pico-sdk') 
PICO.SDK PATH is /home/pi/pico/pico-sdk 


-- Build files have been written to: /home/pi/pico/pico-examples/build 


You can now type make to build all example applications. However, for this example we only need to build blink. To build 
a specific subtree of applications, navigate into the corresponding subtree before running make. In this case, we can build 
only the blink task by first navigating into the blink directory, then running make: 


$ cd blink 

$ make -j4 

Scanning dependencies of target ELF2UF2Build 
Scanning dependencies of target boot. stage2 original 
[ 0%] Creating directories for 'ELF2UF2Build' 


[180%] Linking CXX executable blink.elf 
[100%] Built target blink 


@ TIP 


Invoking make with -j4 speeds the build up by running four jobs in parallel. A Raspberry Pi 5 has four cores, so four 


jobs spreads the build evenly across the entire SoC. 


Amongst other targets, this builds: 


blink.elf 
used by the debugger 
blink.uf2 


the file we'll copy onto RP2040 USB Mass Storage Device 
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3.1.2. Build "Blink" for the Pico W 


Prepare your cmake build directory by running the following command, which specifies that CMake should target the Pico 
W board: 


$ cmake .. -DPICO_BOARD=pico_w 
Using PICO.SDK PATH from environment ('../../pico-sdk') 
PICO. SDK. PATH is /home/pi/pico/pico-sdk 


-- Build files have been written to: /home/pi/pico/pico-examples/build 


@ IMPORTANT 


The SDK builds binaries for the Raspberry Pi Pico by default. To build a binary for a different board, pass the 
-DPICO BOARD-«board» option to CMake, replacing the «board» placeholder with the name of the board you'd like to 


target. To build a binary for Pico W, pass -DPICO BOARD-pico w. To specify a Wi-Fi network and password that your Pico 
W should connect to, pass -DWIFI SSID-"Your Network" -DWIFI PASSWORD-"Your Password". 


You can now type make to build all example applications. However, for this example we only need to build blink. To build 
a specific subtree of applications, navigate into the corresponding subtree before running make. In this case, we can build 
only the blink task by first navigating to pico w/wifi/blink, then running make: 


$ cd pico w/wifi/blink 

$ make -j4 

Scanning dependencies of target ELF2UF2Build 
Scanning dependencies of target boot. stage2 original 
[ 0*] Creating directories for 'ELF2UF2Build' 


[180%] Linking CXX executable picow. blink.elf 
[180%] Built target picow. blink 


9 TIP 


Invoking make with -j4 speeds the build up by running four jobs in parallel. A Raspberry Pi 5 has four cores, so four 


jobs spreads the build evenly across the entire SoC. 


Amongst other targets, this builds: 


picow blink.elf 
used by the debugger 


picow blink.uf2 
the file we'll copy onto RP2040 USB Mass Storage Device 


3.2. Load and run "Blink" 


To load software onto a RP2040-based board, mount it as a USB Mass Storage Device and copy a uf? file onto the board 
to program the flash. 
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Figure 1. Blinking the 
on-board LED on the 
Raspberry Pi Pico. 


Arrows point to the on- 


board LED, and the 
BOOTSEL button. 


Hold down the BOOTSEL button (Figure 1) while plugging in your device using a micro-USB cable to force it into USB Mass 
Storage Mode. 


RP2040 will reboot, unmount itself as a Mass Storage Device, and run the flashed code, see Figure 1. 


3.2.1. Using the command line 


@ TIP 


You can use picotool to load a UF2 binary onto your Raspberry Pi Pico, see Appendix B. 


Depending on the computer you use to compile binaries for your Pico, you may have to mount the mass storage device 
manually: 


$ dmesg | tail 

[ 371.973555] sd 0:0:0:0: [sda] Attached SCSI removable disk 
$ sudo mkdir -p /mnt/pico 

$ sudo mount /dev/sdal /mnt/pico 


If you can see files in /mnt/pico, the USB Mass Storage Device has mounted correctly: 


$ 1s /mnt/pico/ 
INDEX.HTM INFO. UF2.TXT 


Copy your blink.uf2 onto RP2040: 


$ sudo cp blink.uf2 /mnt/pico 
$ sudo sync 


RP2040 automatically disconnects as a USB Mass Storage Device and runs your code, but just to be safe, you should 
unmount manually as well: 
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$ sudo umount /mnt/pico 


@ NOTE 


Removing power from the board does not remove the code. When you restore power to the board, the flashed code 


will run again. 


3.2.2. Aside: Other Boards 
If you are not following these instructions on a Raspberry Pi Pico, you may not have a BOOTSEL button (as labelled in 
Figure 1). Your board may have some other way of loading code, which the board supplier should have documented: 


* Most boards expose the SWD interface (Chapter 5) which can reset the board and load code without any button 
presses 


* There may be some other way of pulling down the flash CS pin (which is how the BOOTSEL button works on 
Raspberry Pi Pico), such as shorting together a pair of jumper pins 


* Some boards have a reset button, but no BOOTSEL; they might detect a double-press of the reset button to enter the 
bootloader 


In all cases you should consult the documentation for the specific board you are using, which should describe the best 
way to load firmware onto that board. 
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Chapter 4. Saying "Hello World" in C 


After blinking an LED on and off, the next thing that most developers will want to do is create and use a serial port, and 
say "Hello World." 


Pico Examples: https://github.com/raspberrypi/pico-examples/blob/master/hello_world/serial/hello_serial.c Lines 10 - 16 


10 int main() ( 


w stdio init all(); 

12 while (true) ( 

13 printf("Hello, world!\n"); 
14 sleep ms(1000); 

15 } 

19. jf 


4.1. Serial input and output on Raspberry Pi Pico 


Serial input (stdin) and output (stdout) can be directed to either serial UART or to USB CDC (USB serial). However by 
default stdio and printf will target the default Raspberry Pi Pico UARTO. 


Default UARTO | Physical Pin | GPIO Pin 


GND 3 N/A 
UARTO_TX 1 GPO 
UARTO_RX 2 GP1 


@ IMPORTANT 


The default Raspberry Pi Pico UART TX pin (out from Raspberry Pi Pico) is pin GPO, and the UART RX pin (in to 
Raspberry Pi Pico) is pin GP1. The default UART pins are configured on a per-board basis using board configuration 


files. The Raspberry Pi Pico configuration can be found in https://github.com/raspberrypi/pico-sdk/blob/master/ 
src/boards/include/boards/pico.h. The SDK defaults to a board name of Raspberry Pi Pico if no other board is 
specified. 


The SDK makes use of CMake to control its build system, see Chapter 8, making use of the pico stdlib interface library 
to aggregate necessary source files to provide capabilities. 


Pico Examples: https://github.com/raspberrypi/pico-examples/blob/master/hello_world/serial/CMakeLists. txt 


1 add_executable(hello_serial 

2 hello_serial.c 

3 ) 

4 

5 # pull in common dependencies 

6 target_link_libraries(hello_serial pico_stdlib) 
y 

8 # create map/bin/hex/uf2 file etc. 

9 pico. add. extra. outputs(hello. serial) 
10 

11 # add url via pico.set. program url 
12 example. auto. set url(hello. serial) 
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The destination for stdout can be changed using CMake directives, with output directed to UART or USB CDC, or to both, 


pico. enable. stdio usb(hello. world 1) © 
pico. enable. stdio uart(hello world 0) © 


1. Enable printf output via USB CDC (USB serial) 
2. Disable printf output via UART 


This means that without changing the C source code, you can change the destination for stdio from UART to USB. 


Pico Examples: https://github.com/raspberrypi/pico-examples/blob/master/hello_world/usb/CMakeLists. txt 


1 if (TARGET tinyusb. device) 

2 add. executable(hello. usb 

8 hello_usb.c 

4 ) 

5 

6 # pull in common dependencies 

7 target_link_libraries(hello_usb pico_stdlib) 
8 

9 # enable usb output, disable uart output 
10 pico. enable. stdio usb(hello usb 1) 

11 pico_enable_stdio_uart(hello_usb 0) 

1122 

13 # create map/bin/hex/uf2 file etc. 

14 pico. add. extra. outputs(hello. usb) 

15 

16 # add url via pico.set program url 

17 example. auto. set url(hello. usb) 

18 elseif(PICO. ON. DEVICE) 

19 message(WARNING "not building hello. usb because TinyUSB submodule is not initialized in 

the SDK") 

20 endif() 


4.2. Build "Hello World" 


As we did for the previous "Blink" example, change directory into the hello world directory inside the pico-examples/build 
tree, and run make. 


$ cd hello. world 

$ make -j4 

Scanning dependencies of target ELF2UF2Build 

[ 0%] Creating directories for 'ELF2UF2Build' 


[ 33%] Linking CXX executable hello. usb.elf 
[ 33%] Built target hello. usb 


[100%] Linking CXX executable hello. serial.elf 
[180%] Built target hello. serial 


This will build two separate examples programs in the hello world/serial/ and hello world/usb/ directories. 
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Figure 2. Connecting 
the Raspberry Pi to 
Raspberry Pi Pico via 
USB. 


Amongst other targets, we have now built: 
* serial/hello serial.elf, which is used by the debugger 
* serial/hello serial.uf2, which can be dragged onto the RP2040 USB Mass Storage Device (UART serial binary) 
* usb/hello usb.elf, which is used by the debugger 
* usb/hello usb.uf2, which can be dragged onto the RP2040 USB Mass Storage Device (USB serial binary) 


Where hello serial directs stdio to UARTO on pins GPO and GP1, and hello usb directs stdio to USB CDC serial. 


© WARNING 


If you have not initialised the tinyusb submodule in your pico-sdk checkout then the USB CDC serial example will not 


work as the SDK will contain no USB functionality. 


4.3. Flash and Run "Hello World" 


Connect the Raspberry Pi Pico to your Raspberry Pi using a micro-USB cable, making sure that you hold down the 
BOOTSEL button to force it into USB Mass Storage Mode. Once it is connected release the BOOTSEL button and if you are 
running the Raspberry Pi Desktop it should automatically mount as a USB Mass Storage Device. From here, you can 
Drag-and-drop either the hello serial.uf2 or hello usb.uf2 onto the Mass Storage Device. 


RP2040 will reboot, unmounting itself as a Mass Storage Device, and start to run the flashed code. 


However, although the "Hello World" example is now running, we cannot yet see the text. We need to connect our host 
computer to the appropriate stdio interface on the Raspberry Pi Pico to see the output. 


4.4. See "Hello World" USB output 


If you have dragged and dropped the hello usb.uf2 binary, then the "Hello World" text will be directed to USB serial. 
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With your Raspberry Pi Pico connected directly to your Raspberry Pi via USB, see Figure 2, you can see the text by 
installing minicom: 
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Figure 3. Enabling a 
serial UART using 
raspi-config on the 
Raspberry Pi. 


$ sudo apt install minicom 
and open the serial port: 
$ minicom -b 115200 -o -D /dev/ttyACMO 


You should see Hello, world! printed to the console. 


@ TIP 


To exit minicom, use CTRL-A followed by X. 


@ NOTE 


If you are intending to using SWD for debugging (see Chapter 6) you need to use a UART based serial connection as 


the USB stack will be paused when the RP2040 cores are stopped during debugging, which will cause any attached 
USB devices to disconnect. 


4.5. See "Hello World" UART output 


Alternatively if you dragged and dropped the hello_serial.uf2 binary, then the "Hello World" text will be directed to 
UARTO on pins GPO and GP1. The first thing you'll need to do to see the text is enable UART serial communications on 
the Raspberry Pi host. To do so, run raspi-conf ig, 


$ sudo raspi-config 


and go to Interfacing Options — Serial and select "No" when asked "Would you like a login shell to be accessible over 
serial?" and "Yes" when asked "Would you like the serial port hardware to be enabled?" You should see something like 
Figure 3. 


File Edit Tabs Help 


Leaving raspi-config you should choose "Yes" and reboot your Raspberry Pi to enable the serial port. 


You should then wire the Raspberry Pi and the Raspberry Pi Pico together with the following mapping: 


mA RA ccc ccc Eccc -——u cL —— À— ————— ÀM—n 
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Raspberry Pi Raspberry Pi Pico 

GND (Pin 14) GND (Pin 3) 

GPIO15 (UART. RXO, Pin 10) GPO (UARTO TX, Pin 1) 
GPIO14 (UART. TXO, Pin 8) GP1 (UARTO RX, Pin 2) 
See Figure 4. 


Figure 4. A Raspberry 
Pi 4 and the Raspberry 
Pi Pico with UARTO 
connected together. 


+ aanse 
sess 


Once the two boards are wired together if you have not already done so you should install minicom: 
$ sudo apt install minicom 

and open the serial port: 
$ minicom -b 115200 -o -D /dev/serial@ 


You should see Hello, world! printed to the console. 


€ TIP 


To exit minicom, use CTRL-A followed by X. 


4.6. Powering the board 


You can unplug the Raspberry Pi Pico from USB, and power the board by additionally connecting the Raspberry Pi's 5V 
pin to the Raspberry Pi Pico VSYS pin via a diode, see Figure 5, where in the ideal case the diode would be a Schottky 
diode. 
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Figure 5. Raspberry Pi 
and Raspberry Pi Pico 
connected only using 

the GPIO pins. 
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Whilst it is possible to connect the Raspberry Pi’s 5V pin to the Raspberry Pi Pico VBUS pin, this is not recommended. 
Shorting the 5V rails together will mean that the Micro USB cannot be used. An exception is when using the Raspberry 
Pi Pico in USB host mode, in this case 5V must be connected to the VBUS pin. 


The 3.3V pin is an OUTPUT pin on the Raspberry Pi Pico, you cannot power the Raspberry Pi Pico via this pin, and it 
should NOT be connected to a power source. 


See the Power section in Hardware design with RP2040 for more information about powering the Raspberry Pi Pico. 


4.6.1. Aside: Hands-free Flash Programming 


You can use the SWD port (Chapter 5) to reset the board and run code. This works even if your code has crashed, 
removing the need to press buttons and unplug. Setting up SWD is a good next step after Hello World. 


If you code Pico programs on a Raspberry Pi, you can set up SWD by running the pico-setup script (Chapter 1) and 
connecting 3 wires from your Pi to the Pico as shown in Chapter 5. You can also use a USB to SWD debug probe, for 
example Appendix A shows how one Pico can be used to access the SWD port of a second Pico via the first Pico’s USB 
port. 
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Chapter 5. Flash Programming with 
SWD 


Serial Wire Debug (SWD) is a standard interface on Cortex-M-based microcontrollers, which the machine you are using 
to develop your code (commonly called the host) can use to reset the board, load code into flash, and set the code 
running. Raspberry Pi Pico exposes the RP2040 SWD interface on three pins at the bottom edge of the board. The host 
can use the SWD port to access RP2040 internals at any time, so there is no need to manually reset the board or hold 
the BOOTSEL button. 


Figure 6. The SWD 
port is labelled at the 
bottom of this Pico 
pinout diagram. The 
ground (GND) 
connection is required 
to maintain good 
signal integrity 
between the host and 
the Pico. The SWDIO 
pin carries debug 
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interface on RP2040, 
so you don't need to 
sacrifice any GPIOs to 
use the SWD port. 


On a Raspberry Pi, you can connect the Pi GPIOs directly to Pico's SWD port, and load code from there. On other 
machines you will need an extra piece of hardware — a debug probe — to bridge a connection on your host machine (like 
a USB port) to the SWD pins on the Pico. One of the cheapest ways to do this is to use another Pico as the debug probe, 
and this is covered in Appendix A. 


This chapter covers how you can connect your machine to Raspberry Pi Pico's SWD port, and use this to write programs 
into flash and run them. 


@ TIP 


If you use an IDE like Visual Studio Code (Chapter 7), this can be configured to use SWD automatically behind the 


scenes, so you click the play button and the code runs, as though you were running native code on your own 
machine. 


@ NOTE 


You can also use SWD for interactive debugging techniques like setting breakpoints, stepping through code 


execution line-by-line, or even peeking and poking IO registers directly from your machine without writing any 
RP2040 software. This is covered in Chapter 6. 


5.1. Installing OpenOCD 
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@ TIP 


If you have run the pico-setup script on your Raspberry Pi (Chapter 1), OpenOCD is already installed and you can skip 


to the next section. 


To access the SWD port on a microcontroller, you need a program on your host machine called a debug translator. 
Debug translators understand the SWD protocol, and know how to control the processor (two Cortex-MO-s in the case 
of RP2040) inside the microcontroller. The debug translator also knows how to talk to the specific debug probe that you 
have connected to the SWD port, and how to program the flash on your device. 


We recommend installing a debug translator called OpenOCD. To install OpenOCD, run the following command: 
$ sudo apt install openocd 


You can run OpenOCD using the openocd command in your terminal. 


5.1.1. Installing OpenOCD on macOS 


To install OpenOCD on macOS, run the following commands: 
$ brew install openocd 


You can run OpenOCD using the openocd command in your terminal. 


5.2. SWD Port Wiring 


You need to connect wires to the SWD port in order to program and run code on RP2040 via SWD. 


Figure 7. A Raspberry 
Pi 4 and the Raspberry 
Pi Pico with UART and 
SWD port connected 
together. Both are 
jumpered directly back 
to the Raspberry Pi 4 
without using a 
breadboard. Only the 
lower three wires in 
this diagram are 
needed for SWD 
access; optionally you 
can also connect the 
Pi UART, as shown by 
the upper 3 wires, to 
directly access the 
Pico's serial port. 


The default configuration is to have SWDIO on Pi GPIO 24, and SWCLK on GPIO 25 — and can be wired to a Raspberry Pi 
Pico with the following mapping, 


5.2. SWD Port Wiring 20 


Getting started with Raspberry Pi Pico 
= 


Raspberry Pi Raspberry Pi Pico 
GND (Pin 20) SWD GND 
GPIO24 (Pin 18) SWDIO 

GPIO25 (Pin 22) SWCLK 


as seen in Figure 7. 


@ TIP 


If you are using another debug probe, like Picoprobe (Appendix A), you need to connect the GND, SWCLK and SWDIO 


pins on your probe to the matching pins on your Raspberry Pi Pico, or other RP2040-based board. 


If possible you should wire the SWD port directly to the Raspberry Pi as signal integrity is important; wiring the SWD port 
via a breadboard or other indirect methods may reduce the signal integrity sufficiently so that loading code over the 
connection is erratic or fails completely. It is important to also wire the ground wire ( OV ) between the two directly and 
not rely on another ground path. 


Note the Raspberry Pi Pico must also be powered (e.g. via USB) in order to debug it! You must build our OpenOCD 
branch to get working multidrop SWD support. 


5.3. Loading a Program 


OpenOCD expects program binaries to be in the form of .e1f (executable linkable format) files, not the .uf2 files used by 
BOOTSEL mode. The SDK builds both types of file by default, but it's important not to mix them up. 


Assuming you have already built the blink example, using the instructions in Chapter 3, you can run the following 
command to program the resulting .e1f file over SWD, and run it: 


$ openocd -f interface/raspberrypi-swd.cfg -f target/rp2040.cfg -c "program blink/blink.elf 
verify reset exit" 


These arguments modify the openocd command in the following ways: 


-f interface/raspberrypi-swd.cfg Tells OpenOCD to use Raspberry Pi's GPIO pins to access the SWD port. To 
use an external USB > SWD probe such as Picoprobe in Appendix A, specify a 
different interface. 


-f target/rp2040.cfg Tells OpenOCD we are connecting to a RP2040-based board. This .cfg file 
contains information for OpenOCD like the type of processor (Cortex-M0+) 
and how it should access the flash memory. 


-c Passes a series of commands to OpenOCD directly from the command line. 
We passed the following commands: 


program blink/blink.elf Tells OpenOCD to write our .elf file into flash, erasing the target region of 
flash first if necessary. The .elf file contains all the information telling 
OpenOCD where different parts of it must be loaded, and how big those parts 
are. 


verify Tells OpenOCD to read back from the flash after programming, to check that 
the programming was successful. 


reset Puts the RP2040 into a clean initial state, as though it just powered up, so 
that it is ready to run our code. 
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exit Disconnects from the RP2040 and exits. The new program will launch when 
OpenOCD disconnects. 


@ NOTE 


To run this command on a Raspberry Pi 5, create a file named raspberrypi5-swd.cfg. Copy and paste the following 
instructions into the file: 


adapter driver linuxgpiod 


adapter gpio swclk 20 -chip 4 
adapter gpio swdio 21 -chip 4 


In the above openocd command, replace interface/raspberrypi-swd.cfg with raspberrypi5-swd.cfg to use the Pi 5-specific 
configuration file. 


@ TIP 


The error Info: DAP init failed indicates that OpenOCD could not see an RP2040 on the SWD interface used. This 
can happen for the following reasons: 


* the board is not powered 


* the SWD wiring is not correct (e.g. the ground wire is disconnected, or SWDIO and SWCLK have been swapped) 


* long or loose jumper wires have damaged signal integrity 


To check that you really have loaded a new program, you can modify blink/blink.c to flash the LED more quickly using 
the following code: 


int main() ( 

const uint LED. PIN = 25; 

gpio. init(LED. PIN) ; 

gpio.set dir(LED PIN, GPIO. OUT); 

while (true) ( 
gpio.put(LED. PIN, 1); 
// Blink faster! (this is the only line that's modified) 
sleep. ms(25); 
gpio.put(LED. PIN, 0); 
sleep. ms(250); 


Then rebuild and rerun the above openocd command to load the new program: 


$ cd pico-examples/build 

$ make blink 

$ openocd -f interface/raspberrypi-swd.cfg -f target/rp2040.cfg -c "program blink/blink.elf 
verify reset exit" 


If the LED blinks faster than before, you have successfully loaded a new program. 
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Chapter 6. Debugging with SWD 


As well as resetting the board, loading and running code, the SWD port on RP2040-based boards like Raspberry Pi Pico 
can be used to interactively debug a program you have loaded. This includes things like: 


* Setting breakpoints in your code 
* Stepping through execution line by line 
* Inspecting the values of variables at different points in the program 


Chapter 5 showed how to install OpenOCD to access the SWD port on your Raspberry Pi Pico. To debug code 
interactively, we also need a debugger, such as the ubiquitous GNU Debugger, GDB. 


Note that by default the SDK builds highly optimised program binaries, which can look very different in terms of control 
flow and dataflow from the original program you wrote. This can be confusing when you try and step through the code 
interactively, so it's often helpful to create a debug build of your program which is less aggressively optimised, so that 
the real on-device control flow is a closer match to your source code. 


6.1. Build "Hello World" debug version 


Q WARNING 


When using SWD for debugging you need to use a UART based serial connection (see Chapter 4) as the USB stack 


will be paused when the RP2040 cores are stopped during debugging, which will cause any attached USB devices to 
disconnect. You cannot use a USB CDC serial connection during debugging. 


You can build a debug version of the "Hello World" with CMAKE BUILD TYPE-Debug as shown below, 


$ cd ~/pico/pico-examples 
$ rm -rf build 
$ mkdir build 


$ cd build 

$ export PICO. SDK PATH-../../pico-sdk 
$ cmake -DCMAKE. BUILD. TYPE-Debug .. 

$ cd hello world/serial 

$ make -j4 


6.2. Installing GDB 


Install gdb-multiarch, 


$ sudo apt install gdb-multiarch 
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@ NOTE 


On Intel Macs, you can install gdb using Homebrew: 


$ brew install gdb 


Despite the warning after installation, you do not have to codesign the binary to use it for remote debugging. 


6.3. Use GDB and OpenOCD to debug Hello World 


Ensuring your Raspberry Pi 4 and Raspberry Pi Pico are correctly wired together, we can attach OpenOCD to the chip, via 
the raspberrypi-swd interface. 


$ openocd -f interface/raspberrypi-swd.cfg -f target/rp2040.cfg 


Your output should look like this: 


Info : rp2040.core0: hardware has 4 breakpoints, 2 watchpoints 
Info : rp2040.core1: hardware has 4 breakpoints, 2 watchpoints 
Info : starting gdb server for rp204@.core@ on 3333 

Info : Listening on port 3333 for gdb connections 


Q WARNING 


If you see an error like Info : DAP init failed then your Raspberry Pi Pico is either powered off, wired incorrectly, or 


has signal integrity issues. Try different GPIO jumper cables. 


This OpenOCD terminal needs to be left open. So go ahead and open another terminal, in this one we'll attach a gdb 
instance to OpenOCD. Navigate to the "Hello World" example code, and start gdb from the command line. 


$ cd -/pico/pico-examples/build/hello. world/serial 
$ gdb-multiarch hello. serial.elf 


Connect GDB to OpenOCD, 


(gdb) target remote localhost:3333 


9 TIP 


You can create a .gdbinit file so you don't have to type target remote localhost:3333 every time. Do this with echo 


"target remote localhost:3333" > ~/.gdbinit. However, this interferes with debugging in VSCode (Chapter 7). 


and load hello serial.elf into flash, 
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(gdb) load 

Loading section .boot2, size 0x100 lma 0x10000000 
Loading section .text, size 0x22d0 lma 0x10000100 
Loading section .rodata, size 0x4a0 lma 0x100023d0 
Loading section .ARM.exidx, size 0x8 lma 0x10002870 
Loading section .data, size 0xb94 lma 0x10002878 
Start address 0x10000104, load size 13324 

Transfer rate: 31 KB/sec, 2664 bytes/write. 


and then start it running. 


(gdb) monitor reset init 
(gdb) continue 


@ IMPORTANT 


If you see errors similar to Error finishing flash operation or Error erasing flash with vFlashErase packet in GDB when 


attempting to load the binary onto the Raspberry Pi Pico via OpenOCD then there is likely poor signal integrity 
between the Raspberry Pi and the Raspberry Pi Pico. If you are not directly connecting the SWD connection between 
the two boards, see Figure 7, you should try to do that. Alternatively you can try reducing the value of adapter_khz in 
the raspberrypi-swd.cfg configuration file, trying halving it until you see a successful connection between the boards. 
As we're bitbanging between the boards timing is marginal, so poor signal integrity may cause errors. 


Or if you want to set a breakpoint at main() before running the executable, 


(gdb) monitor reset init 
(gdb) b main 
(gdb) continue 


Thread 1 hit Breakpoint 1, main () at /home/pi/pico/pico- 
examples/hello_world/serial/hello_serial.c:11 
11 stdio_init_all(); 


before continuing after you have hit the breakpoint, 


(gdb) continue 


To quit from gdb type, 


(gdb) quit 


More information about how to use gdb can be found at https://www.gnu.org/software/gdb/documentation/. 
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Chapter 7. Using Visual Studio Code 


Visual Studio Code (VSCode) is a popular open source editor developed by Microsoft. It is the recommended Integrated 
Development Environment (IDE) on the Raspberry Pi 4 if you want a graphical interface to edit and debug your code. 


7.1. Installing Visual Studio Code 


@ IMPORTANT 


These installation instructions rely on you already having downloaded and installed the command line toolchain (see 


Chapter 3), as well as connecting SWD to your board via OpenOCD (Chapter 5) and setting up GDB for command-line 
debugging (Chapter 6). 


Visual Studio Code (VSCode) can be installed in Raspberry Pi OS using the usual apt procedure: 


$ sudo apt update 
$ sudo apt install code 


Once the install has completed, install the extensions needed to debug a Raspberry Pi Pico: 


$ code --install-extension marus25.cortex-debug 
$ code --install-extension ms-vscode.cmake-tools 
$ code --install-extension ms-vscode.cpptools 


Finally, start Visual Studio Code from a Terminal window: 


$ export PICO. SDK. PATH-/home/pi/pico/pico-sdk 
$ code 


Ensure you set the PICO SDK PATH so that Visual Studio Code can find the SDK. 


@ NOTE 


If PICO_SDK_PATH is not set by default in your shell's environment you will have to set it each time you open a new 


Terminal window before starting VSCode, or start VSCode from the menus. You may therefore want to add it to your 
.profile or .bashrc file. 


@ NOTE 


You can configure intellisense for CMake by changing the provider by toggling; View > Command Palette ^ C/C++: 


Change Configuration Provider... ^ CMake Tools. 


7.2. Loading a Project 


Go ahead and open the pico-examples folder by going to the Explorer toolbar (Ctrl + Shift + E), selecting "Open Folder," 
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Figure 8. Prompt to 
choose the correct 
compiler for the 
project. 


and navigating to, /home/pi/pico/pico-examples in the file popup. Then click "OK" to load the Folder into VSCode. 


As long as the CMake Tools extension is installed, after a second or so you should see a popup in the lower right-hand 
corner of the VSCode window. 


Hit "Yes" to configure the project. You will then be prompted to choose a compiler, see Figure 8, 


Welcome - pico-examples - Code - OSS (headmelted) 
File Edit Selection View Go Run Terminal Help 


Customize 


Recent 


Learn 


> OUTLINE 


> TIM 


and you should select GCC for arm-none-eabi from the drop down menu. 


@ TIP 


If you miss the popups, which will close again after a few seconds, you can configure the compiler by clicking on "No 


Kit Selected" in the blue bottom bar of the VSCode window. 


You can then either click on the "Build" button in the blue bottom bar to build all of the examples in pico-examples folder, 
or click on where it says "[all]" in the blue bottom bar. This will present you with a drop down where you can select a 
project. For now type in "hello_usb" and select the "Hello USB" executable. This means that VSCode will only build the 
"Hello USB" example, saving compile time. 


@ TIP 


You can toggle between building "Debug" and "Release" executables by clicking on where it says "CMake: [Debug]: 


Ready" in the blue bottom bar. The default is to build a "Debug" enabled executable ready for SWD debugging. 


Go ahead and click on the "Build" button (with a cog wheel) in the blue bottom bar of the window. This will create the 
build directory and run CMake as we did by hand in Section 3.1, before starting the build itself, see Figure 9. 
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Figure 9. Building the Welcome - pico-examples - Code - OSS (headmelted) 
pico-examples project File Edit Selection View Go Run Terminal Help 
in Visual Studio Code o EXPLORE [E 


Customize 


O-EXAMPLES 


Learn 


> OUTLINE 
> TIMELINE 


As we did from the command line previously, amongst other targets, we have now built: 
* hello usb.elf, which is used by the debugger 


* hello usb.uf2, which can be dragged onto the RP2040 USB Mass Storage Device 


7.3. Debugging a Project 


The pico-examples repo contains an example debug configuration that will start OpenOCD, attach GDB, and finally launch 
the application CMake is configured to build. Go ahead and copy this file (launch-raspberrypi-swd.json) into the pico- 
examples/.vscode directory as launch.json. We also provide a settings.json file that we recommend you also copy. This 
settings.json removes some potentially confusing options from the CMake plugin (including broken Debug and Run 
buttons that attempt to run a Pico binary on the host). 


$ cd ~/pico/pico-examples 

$ mkdir .vscode 

$ cp ide/vscode/launch-raspberrypi-swd.json .vscode/launch. json 
$ cp ide/vscode/settings.json .vscode/settings.json 


Pico Examples: https://github.com/raspberrypi/pico-examples/blob/master/ide/vscode/launch-raspberrypi-swd.json 


~ 


"version": "0.2.0", 
"configurations": [ 
( 

"name": "Pico Debug", 
"cwd": "S{workspaceRoot}", 
"executable": "S$(command:cmake.launchTargetPath)", 
"request": "launch", 
"type": "cortex-debug", 
"servertype": "openocd", 


OG O0 400 & 0 NA 
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11 // This may need to be "arm-none-eabi-gdb" for some previous builds 
12 "gdbPath" : "gdb-multiarch" 

13 "device": "RP2040", 

14 "configFiles": [ 

15 "interface/raspberrypi-swd.cfg" 

16 "target/rp2040.cfg" 

Tg ll; 

18 "svdFile": "$(env:PICO. SDK. PATH) /src/rp2040/hardware. regs/rp2040.svd" 
19 "runToEntryPoint": "main" 

20 // Work around for stopping at main on restart 

zd "postRestartCommands": [ 

22 "break main" 

23 "continue" 

24 ] 

25 ) 

26 ] 

2E 


You may have to amend the gdbPath in launch.json if your gdb is called arm-none-eabi-gdb instead of gdb-multiarch 


Pico Examples: https://github.com/raspberrypi/pico-examples/blob/master/ide/vscode/settings.json 


1 x 

2 // These settings tweaks to the cmake plugin will ensure 
3 // that you debug using cortex-debug instead of trying to launch 
4 // a Pico binary on the host 

5 "cmake.statusbar.advanced": { 

6 "debug": ( 

7l "visibility": "hidden" 

8 Fo 

9 :Xaunche A 

10 "visibility": "hidden" 

11 je 

12 Module! af 

13 "visibility": "hidden" 

14 In 

1S "buildTarget": { 

16 "visibility": "hidden" 

17 H 

18 m 

19 "cmake.buildBeforeRun": true, 
20 "C. Cpp.default.configurationProvider": "ms-vscode.cmake-tools" 
eu x 


7.3.1. Running "Hello USB" on the Raspberry Pi Pico 
© IMPORTANT 


Ensure that the example "Hello USB" code has been built as a Debug binary (CMAKE BUILD TYPE-Debug). 


Now go to the Debug toolbar (Ctrl + Shift + D) and click the small green arrow (play button) at the top of the left-hand 
window pane to load your code on the Raspberry Pi Pico and start debugging. 
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Figure 10. Debugging hello_world.c - pico-examples - Code - OSS (headmelted) vax 
the "Hello USB" binary dit t 
inside Visual Studio 
Code 


Lnl2,Coll Spaces4 UTF-8 LF C Æ Q 


The code should now be loaded on to the Raspberry Pi Pico, and you should see the source code for "Hello USB" in the 
main right-hand (upper) pane of the window. The code will start to run and it will proceed to the first breakpoint — 
enabled by the runTollain directive in the launch.json file. Click on the small blue arrow (play button) at the top of this 
main source code window to Continue (F5) and start the code running. 


@ TIP 


If you switch to the "Terminal" tab in the bottom right-hand pane, below the hello_usb.c code, you can use this to 
open minicom inside VSCode to see the UART output from the "Hello USB" example by typing, 


$ minicom -b 115200 -o -D /dev/ttyACMO 


at the terminal prompt as we did before, see Section 4.4. 
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Chapter 8. Creating your own Project 


Go ahead and create a directory to house your test project sitting alongside the pico-sdk directory, 


$ ls -la 
total 16 
drwxr-xr-x 7 aa staff 224 6 Apr 10:41 ./ 
drwx---2-- @ 27 aa staff 864 6 Apr 10:41 ../ 


drwxr-xr-x 10 aa staff 320 6 Apr 09:29 pico-examples/ 
drwxr-xr-x 13 aa staff 416 6 Apr 09:22 pico-sdk/ 

$ mkdir test 

$ cd test 


and then create a test.c file in the directory, 


#include <stdio.h> 

#include "pico/stdlib.h" 
#include "hardware/gpio.h" 
#include "pico/binary info.h" 


const uint LED. PIN = 25;@ 
int main() ( 


bi .decl(bi. program description("This is a test binary."));@ 
bi decl(bi 1pin.with. name(LED. PIN, "On-board LED")); 


stdio. init all(); 


gpio. init(LED. PIN); 
gpio.set dir(LED. PIN, GPIO. OUT); 
while (1) ( 

gpio.put(LED. PIN, 0); 

sleep. ms(250); 


EN mE cA mA qm mA LA nA mA c5 
') 0 4100 0 l0 000-1007 0n | 


20 gpio.put(LED. PIN, 1); 
gn puts("Hello World in"); 
22 sleep ms(1000); 

23 } 

24 } 


@ The onboard LED is connected to GP25 on Pico, if youre — (2) These lines will add strings to the binary visible using 
building for Pico W the LED is connected to picotool, see Appendix B. 
CYW43 WL GPIO LED PIN. For more information see the Pico W 
blink example in the Pico Examples Github repository. 


along with a CMakeLists.txt file, 


cmake. minimum required(VERSION 3.13) 
include(pico. sdk  import.cmake) 


project(test. project C CXX ASM) 
set(CMAKE. C. STANDARD 11) 
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Set(CMAKE. CXX STANDARD 17) 
pico.sdk. init() 


add. executable(test 
test.c 


pico. enable. stdio usb(test 1)@ 
pico. enable. stdio uart(test 1)@ 


pico. add. extra. outputs(test) 


target link libraries(test pico. stdlib) 


1. This will enable serial output via USB. 
2. This will enable serial output via UART. 


Then copy the pico sdk import.cmake file from the external folder in your pico-sdk installation to your test project folder. 


$ cp ../pico-sdk/external/pico. sdk import.cmake . 


You should now have something that looks like this, 


$ ls -la 

total 24 

drwxr-xr-x 5 aa staff 160 6 Apr 10:46 ./ 

drwxr-xr-x 7 aa staff 224 6 Apr 10:41 ../ 

-rw-r--r--@ 1 aa staff 394 6 Apr 10:37 CMakeLists.txt 
-rw-r--r-- 1 aa staff 2744 6 Apr 10:40 pico.sdk import.cmake 
-rw-r--r-- 1 aa staff 383 6 Apr 10:37 test.c 


and can build it as we did before with our "Hello World" example. 


mkdir build 

cd build 

export PICO. SDK PATH-../../pico-sdk 
cmake .. 


U D dps G Spy 


make 


@ IMPORTANT 


The SDK builds binaries for the Raspberry Pi Pico by default. To build a binary for a different board, pass the 
-DPICO BOARD-«board» option to CMake, replacing the «board» placeholder with the name of the board you'd like to 


target. To build a binary for Pico W, pass -DPICO BOARD-pico w. To specify a Wi-Fi network and password that your Pico 
W should connect to, pass -DWIFI SSID-"Your Network" -DWIFI PASSWORD-"Your Password". 


The make process will produce a number of different files. The important ones are shown in the following table. 


File extension Description 
.bin Raw binary dump of the program code and data 
.elf The full program output, possibly including debug information 
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File extension Description 


.uf2 The program code and data in a UF2 form that you can drag-and-drop on to the RP2040 
board when it is mounted as a USB drive 


.dis A disassembly of the compiled binary 
.hex Hexdump of the compiled binary 
.map A map file to accompany the .elf file describing where the linker has arranged segments 
in memory 
O NOTE 


UF2 (USB Flashing Format) is a file format, developed by Microsoft, that is used for flashing the RP2040 board over 


USB. More details can be found on the Microsoft UF2 Specification Repo 


@ NOTE 


To build a binary to run in SRAM, rather than Flash memory you can either setup your cmake build with 
-DPICO_NO_FLASH=1 or you can add pico_set_binary_type(TARGET_NAME no_flash) to control it on a per binary basis in your 
CMakeLists.txt file. You can download the RAM binary to RP2040 via UF2. For example, if there is no flash chip on 
your board, you can download a binary that runs on the on-chip RAM using UF2 as it simply specifies the addresses 
of where data goes. Note you can only download in to RAM or FLASH, not both. 


8.1. Debugging your project 


Debugging your own project from the command line follows the same processes as we used for the "Hello World" 
example back in Section 6.3. Connect your Raspberry Pi and the Raspberry Pi Pico as in Figure 11. 


Figure 11. A Raspberry 
Pi 4 and the Raspberry 
Pi Pico with UART and 
SWD debug port 
connected together. 
Both are jumpered 
directly back to the 
Raspberry Pi 4 without 
using a breadboard. 


Then go ahead and build a debug version of your project using CMAKE BUILD TYPE-Debug as below, 


$ cd ~/pico/test 
$ rmdir build 

$ mkdir build 

$ cd build 
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$ export PICO. SDK PATH-../../pico-sdk 
$ cmake -DCMAKE. BUILD. TYPE-Debug .. 
$ make 


@ IMPORTANT 


The SDK builds binaries for the Raspberry Pi Pico by default. To build a binary for a different board, pass the 
-DPICO BOARD-«board» option to CMake, replacing the «board» placeholder with the name of the board you'd like to 


target. To build a binary for Pico W, pass -DPICO BOARD-pico w. To specify a Wi-Fi network and password that your Pico 
W should connect to, pass -DWIFI SSID-"Your Network" -DWIFI PASSWORD-"Your Password". 


Then open up a terminal window and attach OpenOCD using the raspberrypi-swd interface. 
$ openocd -f interface/raspberrypi-swd.cfg -f target/rp2040.cfg 


This OpenOCD terminal needs to be left open. So go ahead and open another terminal window and start gdb-multiarch 
using 


$ cd ~/pico/test/build 
$ gdb-multiarch test.elf 


Connect GDB to OpenOCD, and load the test.elf binary into flash, 


(gdb) target remote localhost:3333 
(gdb) load 


and then start it running, 


(gdb) monitor reset init 
(gdb) continue 


8.2. Working in Visual Studio Code 


If you want to work in Visual Studio Code rather than from the command line you can do that, see Chapter 7 for 
instructions on how to configure the environment and load your new project into the development environment to let 
you write and build code. 


If you want to also use Visual Studio Code to debug and load your code onto the Raspberry Pi Pico you'll need to create 
a launch. json file for your project. The example launch-raspberrypi-swd.json in Chapter 7 should work. You need to copy it 
into your project directory as .vscode/launch.json. 


8.3. Automating project creation 


The pico project generator, automatically creates a "stub" project with all the necessary files to allow it to build. If you 
want to make use of this you'll need to go ahead and clone the project creation script from its Git repository, 
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$ git clone https://github.com/raspberrypi/pico-project-generator.git --branch master 


It can then be run in graphical mode, 


$ cd pico-project-generator 


$ ./pico.project.py --gui 


which will bring up a GUI interface allowing you to configure your project, see Figure 12. 


Figure 12. Creating a Raspberry Pi Pico Project Generator 


RP2040 project using 
the graphical project 
creation tool. 


es Raspberry Pi 


Project Name : IProjectName 


Location : //home/jamesh/projects/gitlab/pico project Browse 


Library Options. 


|^ SPI [- PIO interface 
|C 12C interface [- HW interpolation 
|^ DMA support [- HW timer 


F HW watchdog 
^ HW clocks 


-Console Options 


| Bi Console over UART [ Console over USB (Disables other USB use) 


-Code Options. 


[^ Add examples for Pico library 


| C Enable C++ exceptions 


[- Run from RAM [7 Generate C++ Advanced... | 


[- Enable C++ RTTI 


-Build Options. 


[- Run build after generation |^ Overwrite project if it already exists 


-IDE Options. 


Create VSCode project Debugger: |SWD 


You can add specific features to your project by selecting them from the check boxes on the GUI. This will ensure the 
build system adds the appropriate code to the build, and also adds simple example code to the project showing how to 


use the feature. 


There are a number of options available, which provide the following functionality. 


Console Options 


Description 


Console over UART 


Enable a serial console over the UART. This is the default. 


Console over USB 


Enable a console over the USB. The device will act as a USB serial port. This 
can be used in addition to or instead of the UART option, but note that when 
enabled other USB functionality is not possible. 


Code Options 


Description 


Add examples for Pico library 


Example code will be generated for some of the standard library features that 
by default are in the build, for example, UART support and HW dividers. 
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Code Options 


Description 


Run from RAM 


Usually, the build creates a binary that will be installed to the flash memory. 
This forces the binary to work directly from RAM 


Generate C++ 


The source files generated will be C++ compatible. 


Enable C++ exceptions 


Enable C++ exceptions. Normally disabled to save code space. 


Enable C++ RTTI 


Enable C++ Run Time Type Information. Normally disabled to save code 
space. 


Advanced Brings up a table allowing selection of specific board build options. These 
options alter the way the features work, and should be used with caution. 

Build Options Description 

Run Build Once the project has been created, build it. This will produce files ready for 


download to the Raspberry Pi Pico. 


Overwrite Project 


If a project already exists in the specified folder, overwrite it with the new 
project. This will overwrite any changes you may have made. 


IDE Options 


Description 


Create VSCode Project 


As well as the CMake files, also create the appropriate Visual Studio Code 
project files. 


Debugger 


Select which Pico Debugger the VSCode debugging system will use. Defaults 
to Serial Wire Debug. 


8.3.1. Project generation from the command line 


The script also provides the ability to create a project from the command line, e.g. 


$ export PICO. SDK. PATH-" /home/pi/pico/pico-sdk" 
$ ./pico.project.py --feature spi --feature i2c --project vscode test 


The --feature options add the appropriate library code to the build, and also example code to show basic usage of the 


feature. You can add multiple features, up to the memory limitation of the RP2040. You can use the --1ist option of the 


script to list all the available features. The example above adds support for the I2C and SPI interfaces. 


Here passing the --project vscode option will mean that .vscode/launch.json, .vscode/c cpp properties.json and 
.vscode/settings. json files are also created, in addition to the CMake project files. 


Once created you can build the project in the normal way from the command line, 


$ cd test/build 
$ cmake .. 
$ make 


ee] 
8.3. Automating project creation 36 


Getting started with Raspberry Pi Pico 


@ IMPORTANT 


The SDK builds binaries for the Raspberry Pi Pico by default. To build a binary for a different board, pass the 
-DPICO BOARD-«board» option to CMake, replacing the «board» placeholder with the name of the board you'd like to 


target. To build a binary for Pico W, pass -DPICO BOARD-pico w. To specify a Wi-Fi network and password that your Pico 
W should connect to, pass -DWIFI SSID-"Your Network" -DWIFI PASSWORD-"Your Password". 


or from Visual Studio Code. 


You can use the --help option to give a list of command line arguments, these will also be applied when using the 
graphical mode. 


Need more detail? 


There should be enough here to show you how to get started, but you may find yourself wondering why 
some of these files and incantations are needed. The Raspberry Pi Pico C/C++ SDK book dives deeper 
into how your project is actually built, and how the lines in our CMakeLists.txt files here relate to the 
structure of the SDK, if you find yourself wanting to know more at some future point. 
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Chapter 9. Building on other 
platforms 


While the main supported platform for developing for the RP2040 is the Raspberry Pi, support for other platforms, such 
as Apple macOS and Microsoft Windows, is available. 


9.1. Building on Apple macOS 


Using macOS to build code for RP2040 is very similar to Linux. 


9.1.1. Installing the Toolchain 


Installation depends on Homebrew. If you don't have it installed, install it: 


$ /bin/bash -c "S(curl -fsSL 
https://raw.githubusercontent.com/Homebrew/install/master/install.sh)" 


Then, install the toolchain: 


$ brew install cmake 
$ brew tap ArmMbed/homebrew-formulae 
$ brew install gcc-arm-embedded 


Now, you can follow the instructions to build code for the RP2040. Once you've installed the toolchain, developing on 
macOS and Linux behave the same. 


See Section 2.1 and follow the instructions from there — skipping the section where you install the toolchain — to fetch 
the SDK and build the "Blink" example. 


9.1.2. Using Visual Studio Code 


Visual Studio Code (VSCode) is a cross platform environment that runs on macOS, Linux, and Microsoft Windows. 
Download the macOS version and install it into to your Applications folder. 


To start Visual Studio Code, click the VSCode icon in your Applications folder. 


9.1.3. Building with CMake Tools 


After starting Visual Studio Code, install the CMake Tools extension. Click on the Extensions icon in the left-hand 
toolbar (or type Cmd + Shift X) and search for "CMake Tools". Click the "CMake Tools" entry in the list, then click the 
install button. 


We now need to set the PICO SDK PATH environment variable. Navigate to the pico-examples directory and create a .vscode 
directory and add a file called settings.json to tell CMake Tools to location of the SDK. Additionally point Visual Studio at 
the CMake Tools extension. 
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Figure 13. Prompt to 
choose a compiler for 
your project. 


"cmake.environment": { 
"PICO.SDK PATH ;"..f..fpico-sdk" 
Um 


Now click on the Cog Wheel at the bottom of the navigation bar on the left-hand side of the interface and select 
Settings. Then, in the Settings pane, click on Extensions » CMake Tools. Then scroll down to Cmake: Generator and 
enter "Unix Makefiles" into the box. 


@ NOTE 


Depending on your local setup you may not need to set the CMake generator manually to "Unix Makefiles". However 
if you do not do so in some cases Visual Studio will default to ninja rather than make and the build might fail as GCC 
outputs dependency-information in a slightly-incorrect format that ninja can’t understand. 


If you do find yourself having to configure this variable manually, you may need to point Visual Studio at the CMake 
Tools extension explicitly by adding the following additional configurationProvider line to your settings. json file: 


"cmake.environment": { 
"PICO. SDK PATH": "../../pico-sdk" 
}, 


"C_Cpp.default.configurationProvider": "ms-vscode.cmake-tools" 


Then, go to the File menu and click on Add Folder to Workspace.... Navigate to and select the pico-examples repo. The 
project will load and you'll (probably) be prompted to choose a compiler, see Figure 13. Select Clang... as your compiler. 
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Finally, click on the Build button at the bottom of the window. This will create the build directory and run CMake as we 
did by hand in Section 3.1, before starting the build itself, see Figure 9. 


This will produce elf, bin, and uf2 targets, you can find these in the hello_world/serial and hello_world/usb directories 
inside the newly created build directory. The UF2 binaries can be dragged and dropped directly onto a RP2040 board 
attached to your computer using USB. 
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9.1.4. Saying "Hello World" 


As we did previously in Chapter 4 ,you can build the Hello World example with stdio routed either to USB CDC (Serial) or 
to UARTO on pins GPO and GP1. No driver installation is necessary if you're building with USB CDC as the target output, 
as it's a class-compliant device. Use a Terminal program, such as Serial, to connect to the USB serial port. 


9.1.4.1. UART output 


Alternatively, if you want to you want to connect to the Raspberry Pi Pico standard UART to see the output you will need 
to connect your Raspberry Pi Pico to your Mac using a USB to UART Serial converter, for example a SparkFun FTDI 
Basic board. For more information, see Figure 14. 


Figure 14. Sparkfun 
FTDI Basic adaptor 
connected to the 
Raspberry Pi Pico 
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So long as you're using a recent version of macOS, the drivers should already be loaded. Otherwise see the 
manufacturers’ website for FTDI Chip Drivers. 


Then, use a Terminal program, such as Serial, to connect to the USB serial port. 


9.2. Building on MS Windows 


Installing the toolchain on Microsoft Windows 10 or Windows 11 is somewhat different to other platforms. However 
once installed, building code for the RP2040 is somewhat similar. 
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Figure 15. Installing 
the Raspberry Pi Pico 
SDK using the 
Windows Pico 
Installer. 


Q WARNING 


Using Raspberry Pi Pico with Windows 7 or 8 is not officially supported but can be made to work. 


9.2.1. Installing the Toolchain 


If you are developing for Raspberry Pi Pico on Microsoft Windows, installation of the toolchain can be done using the 
Windows Pico Installer. 


Go ahead and download the latest release of the installer from Github, https://github.com/raspberrypi/pico-setup- 
windows, and run it. The installation wizard, see Figure 15, will guide you through installing the toolchain. 
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After the wizard has completed installation it will prompt you whether it should display a tutorial, and optionally clone 
and build the pico-examples repository from Github. 


Included software: 
* Arm GNU Toolchain 
* CMake 
* Ninja 
* Python 3.9 
* Git for Windows 
* Visual Studio Code 


* OpenOCD 


9.2.1.1. Starting Visual Studio Code 


In your Start Menu, look for the Pico - Visual Studio Code shortcut, in the Raspberry Pi Pico SDK «version» folder. The 
shortcut sets up the needed environment variables and then launches Visual Studio Code. 
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@ NOTE 


If you have previously had Visual Studio Code installed we often see problems due to random settings inserted by 


other extensions, or by the user, in an existing installation. If this is the case for you, please go to the Pico Installer 
Wiki for a checklist of known issues and solutions. 


9.2.1.2. Opening the examples 


The first time you launch Visual Studio Code using the Start Menu shortcut, it will open the pico-examples repository. 


To re-open the examples repository later, you can open the copy installed at C:\ProgramData\Raspberry Pi\Pico SDK 


«version» Mpico-examples. 


9.2.1.3. Building the examples 


Visual Studio Code will ask if you want to configure the pico-examples project when it is first opened; click Yes on that 
prompt to proceed. (If you miss the prompt look for the ‘bell’ icon in the bottom right.) You will then be prompted to 
select a kit — select the Pico ARM GCC - Pico SDK Toolchain with GCC arm-none-eabi entry. If the Pico ARM GCC entry is 
not present, select Unspecified to have the SDK auto-detect the compiler. 


Figure 16. Visual 
Studio code and the 
pico-examples 
repository. 
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To build one of the examples, click the "CMake" button on the sidebar. You should be presented with a tree view of the 
example projects; expand the project you'd like to build, and click the small build icon to the right of the target name to 
build that specific project. 


To build everything instead, click the "Build All Projects" button at the top of the CMake Project Outline view. 


@ NOTE 


You can find more information about how to use Visual Studio Code in the Pico Setup for Windows tutorial. 


@ IMPORTANT 


If you are having problems installing or using the toolchain under Windows there is a troubleshooting guide available 


on the Pico Setup for Windows GitHub repository. 


9.2.2. Alternative manual installation 
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Q WARNING 


Manual installation of the toolchain under MS Windows is complicated and not recommended. 


To build you will need to install some extra tools. 


* Arm GNU Toolchain (you need the filename ending with -arm-none-eabi .exe) 


CMake 


Build Tools for Visual Studio 2022 


Python 3.10 
* Git 


Download the executable installer for each of these from the links above, and then carefully follow the instructions in 
the following sections to install all five packages on to your Windows computer. 


9.2.2.1. Installing Arm GNU Toolchain 


Figure 17. Installing 
the Arm GNU 
Toolchain. Ensure that 
you register the path 


to the compiler as an 
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During installation you should tick the box to register the path to the Arm compiler as an environment variable in the 
Windows shell when prompted to do so. 


9.2.2.2. Installing CMake 
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Figure 18. Installing 
CMake. 


During the installation add CMake to the system PATH for all users when prompted by the installer. 


28g: Manage Downloads 


Home Share View Application Tools 


~ A > ThisPC > Downloads 


Name ^ 
a Quick access 
Bil Desktop 


& Downloads 


B] cmake-323.2-windows-x86 64.msi 


© Git-236.1-64-bitexe. 


Documents B» python-3.10,5-amdé4.exe 
© Pictures 06 vs BuildTools.exe 
D Music 


(i gec-arm-11.2-2022.02-mingw-w64-i686-... 


Date modified 


08/06/2022 17:33 
08/06/2022 17:32 
(08/06/2022 17:35 
08/06/2022 17:34 
08/06/2022 17:33 


vo 


E Install Options 
Install Options 
Choose options for instaling CMake 3.23.2 


By default CMake does not add its drectory to the system PATH. 


O Do not add CMake to the system PATH 
Add Cake tothe system PATH forall users) 
O Add CMake to the system PATH for the current user 


[Create CMake Desktop Icon 


Search Downloads 


Type 


Windows Installer... 
Application 
Application 
Application 
Application 


Size 


28,588 KB 
559,993 KB 
48,475 KB 
27,967 KB 
1,642 KB 


9.2.2.3. Installing Build Tools for Visual Studio 2022 


Figure 19. Installing 
the Build Tools for 
Visual Studio 2022. 


Installing — Visual Studio Build Tools 2022 — 17.2.3 
Workloads Individual components ^ Language packs 


© Need help choosing what to install? More info 


Desktop & Mobile (4) 


Desktop development with C++ 
Build modern C++ apps for Windows using tools of your 
choice, including MSVC, Clang, CMake, or MSBuild. 


NET desktop build tools 
Tools for building WPF, Windows Forms, and console 
applications using C, Visual Basic, and Fé 


Web & Cloud (4) 


e Web development build tools. 
MSBuild tasks and targets for building web applications. 


Location 
C:\Program Files (x86)\Microsoft Visual Studio\2022\BuildTools Change 


Installation locations 


Mobile Development with NET 
Tools for building cross-platform applications for iOS, 
Android and Windows using C# and Fe, 


IB. Universal Windows Platform build tools 
WW provides the tools required to build Universal Windows: 
Platform applications. 


‘Azure development build tools 
MSBuild tasks and targets for building Azure applications. 


By continuing, you agree to the license for the Visual Studio edition you selected. We also offer the ability to download other software with Visual 
Studio. This software is licensed separately, as set out in the 3rd Party Notices or in its accompanying license. By continuing, you also agree to those 


licenses. 


Installation details 


7 Desktop development with C++ 
~ Included 
M. C++ Build Tools core features 
Y C++ 2022 Redistributable Update 
Y Ce core desktop features 
~ Optional 
MSVC v143 - VS 2022 C++ 64/186 build t. 
Windows 10 SDK (10.0.19041.0) 
C++ CMake tools for Windows 
Testing tools core features - Build Tools. 
C++ AddressSanitizer 
C++ ATL for latest v143 build tools (x86 8. 
C++ MFC for latest v143 build tools (x86... 
C++/CLI support for v143 build tools (Late. 
C++ Modules for v143 build tools (x64/x8.. 
C++ Clang tools for Windows (13.0.1 - x64. 
Windows 11 SDK (10.022621.0) 
Windows 11 SDK (10.0.220000) 
Windows 10 SDK (10.020348.0) 


Windows 10 SDK (10.0.18362.0 


Total space required 7.47 GB 


Install while downloading ~ | Install 


pri 
valid for 


When prompted by the Build Tools for Visual Studio installer you need to install the C++ build tools only. 
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@ NOTE 


You must install the full "Windows 10 SDK" package as the SDK will need to build the pioasm and elf2uf2 tools locally. 


Removing it from the list of installed items will mean that you will be unable to build Raspberry Pi Pico binaries. 


9.2.2.4. Installing Python 3.10 


During the installation, ensure that it's installed ‘for all users' and add Python 3.10 to the system PATH when prompted by 
the installer. You should additionally disable the MAX PATH length limit when prompted at the end of the Python 
installation. 


Figure 20. Installing 
Python 3.10 tick the 
"Add Python 3.10 to 
PATH" box. 


€ Bn Manage 
Home ^ Share View Application Tools 
vOv db > ThisPC > Downloads w © Search Downloads 
Name i Date modified Type Sie 
5k Quick access 
Bil Desktop 
4) Downloads 


B) cmake-3232-windows-x86 64. msi. 08/06/2022 1733 ^ Windows Installer 28,588 KB 
Qi gce-arm-11,2-2022.02-mingw-w64-i686-.. 08/06/2022 17:32 Application 559.993 KB 
4» Git-2.36.1-64-bit.exe. 08/06/2022 17:35 Application 48475 KB 
[E] Documents BÀ python-3.10.5-amd6d.exe 08/06/2022 1734 Application 27,967 KB 
© Pictures M vs BuildTools.exe 08/06/2022 17:33 Application 1,642 KB 
J Music 


I. Python 3.10.5 (64-bit) Setup 


Install Python 3.10.5 (64-bit) 


Select Install Now to install Python with default settings, or choose 
Customize to enable or disable features. 


@ Install Now 
CCAUsers\IEUser\AppData\Local\Programs\Python\Python310 


Includes IDLE, pip and documentation, 
Creates shortcuts and file associations 


— Customize installation 
Choose location and features 


EZ Install launcher for all users (recommended) 


Add Python 3.10 to PATH 


9.2.2.5. Installing Git 


When installing Git you should ensure that you change the default editor away from vim, see Figure 21. 


Figure 21. Installing 
Git 


+i AQ! Manage Downloads 
Home Share — View Application Tools 
~ > ThisPC > Downloads v © Search Downloads 
Name ^ Date modified Type Sie 
a Quick access 
I Desktop 
& Downloads 


d cmake-3.23,2-windows-x86_64.msi 08/06/2022 17:33 Windows Installer .. 28,588 KB 
(ib gcc-arm-11.2-2022.02-mingw-w64-i686-... — 08/06/2022 17:32 Application 559,993 KB. 
A> Git-2.36.1-64-bit.exe (08/06/2022 17:35 Application. 48,475 KB 
E Documents > python-3.10.5-amd64.exe 08/06/2022 17:34 Application 27,967 KB 
© Pictures 06 vs_BuildTools.exe 08/06/2022 17:33 Application 4,642 KB 
D Music 


4» Git 236.1 Setup 


Choosing the default editor used by Git. 
Which editor would you lke Git to use? 


[Use Vim (the ubiquitous text editor) as Gis default editor 
[Use Vm (the ubiquitous text editor) as Gits default editor 
[Use Notepad++ as Gs defaut editor 

[Use Visual Studio Code as Gits default editor 

Use Visual Studio Code Insiders as Git's default editor 
[Use Sublme Text as Gits default editor 

Use Atom as is default editor 
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Ensure you tick the checkbox to allow Git to be used from 3rd-party software and, unless you have a strong reason 
otherwise, when installing Git you should also check the box "Checkout as is, commit as-is", select "Use Windows' 
default console window", and "Enable experimental support for pseudo consoles" during the installation process. 


9.2.2.6. Getting the SDK and examples 


C:\Users\pico\Downloads> git clone https://github.com/raspberrypi/pico-sdk.git --branch master 
C:\Users\pico\Downloads> cd pico-sdk 

C:\Users\pico\Downloads\pico-sdk> git submodule update --init 
C:\Users\pico\Downloads\pico-sdk> cd .. 

C:\Users\pico\Downloads> git clone https://github.com/raspberrypi/pico-examples.git --branch 
master 


9.2.2.7. Building "Hello World" from the Command Line 
Go ahead and open a Developer Command Prompt window from the Windows Menu, by selecting Windows » Visual 
Studio 2022 > Developer Command Prompt for VS 2022 from the menu. 


Then set the path to the SDK as follows, 


C:\Users\pico\Downloads> setx PICO. SDK PATH "..\..\pico-sdk" 


You now need to close your current Command Prompt window and open a second Developer Command Prompt 
window where this environment variable will now be set correctly before proceeding. 


Navigate into the pico-examples folder, and build the 'Hello World' example as follows, 


C:\Users\pico\Downloads> cd pico-examples 
C:\Users\pico\Downloads\pico-examples> mkdir build 
C:\Users\pico\Downloads\pico-examples> cd build 
C:\Users\pico\Downloads\pico-examples\build> cmake -G "NMake Makefiles" 
C:\Users\pico\Downloads\pico-examples\build> nmake 


@ IMPORTANT 


The SDK builds binaries for the Raspberry Pi Pico by default. To build a binary for a different board, pass the 
-DPICO BOARD-«board» option to CMake, replacing the «board» placeholder with the name of the board you'd like to 


target. To build a binary for Pico W, pass -DPICO BOARD-pico w. To specify a Wi-Fi network and password that your Pico 
W should connect to, pass -DWIFI SSID-"Your Network" -DWIFI PASSWORD-"Your Password". 


to build the target. This will produce elf, bin, and uf2 targets, you can find these in the hello world/serial and 
hello world/usb directories inside your build directory. The UF2 binaries can be dragged-and-dropped directly onto a 
RP2040 board attached to your computer using USB. 


9.2.2.8. Building "Hello World" from Visual Studio Code 


Now you've installed the toolchain you can install Visual Studio Code and build your projects inside the that environment 
rather than from the command line. 


Go ahead and download and install Visual Studio Code for Windows. After installation open a Developer Command 


E] 
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Figure 22. Setting 
PICO SDK PATH 
Environment Variable 
in the CMake 
Extension 


Prompt window from the Windows Menu, by selecting Windows » Visual Studio 2022 » Developer Command Prompt for VS2022 
from the menu. Then type, 


C:» code 


at the prompt. This will open Visual Studio Code with all the correct environment variables set so that the toolchain is 
correctly configured. 


© WARNING 


If you start Visual Studio Code by clicking on its desktop icon, or directly from the Start Menu then the build 
environment will not be correctly configured. Although this can be done manually later in the CMake Tools settings, 


the easiest way to configure the Visual Studio Code environment is just to open it from a Developer Command 
Prompt window where these environmental variables are already set. 


We'll now need to install the CMake Tools extension. Click on the Extensions icon in the left-hand toolbar (or type Ctrl + 
Shift + X), and search for "CMake Tools" and click on the entry in the list, and then click on the install button. 


Then click on the Cog Wheel at the bottom of the navigation bar on the left-hand side of the interface and select 
"Settings". Then in the Settings pane click on "Extensions" and then "CMake Tools". Then scroll down to "Cmake: 
Configure Environment". Click on "Add Item" and set the PICO SDK PATH to be ..\..\pico-sdk as in Figure 22. 


= Settings 


cmake 
Cmake: Configure Args 
Additional arguments to pass to CI 


Add Item 


e: Configure Environment 


Configure On Edit 


Automatically configure CMake project 


Configure On Open 
utomatically configure CMake proje 


Cmake: Configure Settings 


Copy Compile Commands 


Additionally you will need to scroll down to "Cmake: Generator" and enter "NMake Makefiles" into the box. 


@ IMPORTANT 


If you do not change the "Cmake: Generator" Visual Studio will default to ninja and the build might fail as GCC 


outputs dependency-information in a slightly-incorrect format that ninja can’t understand. 


Now close the Settings page and go to the File menu and click on "Open Folder" and navigate to pico-examples repo and 
click "Select Folder". You'll be prompted to configure the project, see Figure 23. Select "GCC for arm-none-eabi" for your 
compiler. 
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Figure 23. Prompt to 
configure your project EXPLORER z Welcome X 
in Visual Studio Code. 


audio 


build 


docks 


OUTLINE 
TIMELINE 
@040 © CMake: [Debug]: Ready X No Kit Selected Build [al] D 


Go ahead and click on the "Build" button (with a cog wheel) in the blue bottom bar of the window. This will create the 
build directory and run CMake and build the examples project, including "Hello World". 


This will produce elf, bin, and uf2 targets, you can find these in the hello world/serial and hello world/usb directories 
inside the newly created build directory. The UF2 binaries can be dragged-and-dropped directly onto a RP2040 board 
attached to your computer using USB. 


9.2.2.9. Flashing and Running "Hello World" 


Connect the Raspberry Pi Pico to your Raspberry Pi using a micro-USB cable, making sure that you hold down the 
BOOTSEL button to force it into USB Mass Storage Mode. The board should automatically appear as a external drive. You 
can now drag-and-drop the UF2 binary onto the external drive. 


The Raspberry Pi Pico will reboot, and unmount itself as an external drive, and start running the flashed code. 


As we did in Chapter 4 you can build the Hello World example with stdio routed either to USB CDC (Serial) or to UARTO 
on pins GPO and GP1. No driver installation is necessary if you're building with USB CDC as the target output, as it's a 
class-compliant device. 


9.2.2.9.1. UART output 


Alternatively if you want to you want to connect to the Raspberry Pi Pico standard UART to see the output you will need 
to connect your Raspberry Pi Pico to your computer using a USB to UART Serial converter, for example a SparkFun FTDI 
Basic board, see Figure 24. 
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Figure 24. Sparkfun 
FTDI Basic adaptor 
connected to the 
Raspberry Pi Pico 
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So long as you're using a recent version of Windows 10, the appropriate drivers should already be loaded. Otherwise see 
the manufacturers' website for FTDI Chip Drivers. 


Then if you don't already have it, download and install PuTTY. Run it, and select "Serial", enter 115,200 as the baud rate 
in the "Speed" box, and the serial port that your UART converter is using. If you don't know this you can find out using 
the chgport command, 


C:» chgport 
COMA \Device\ProlificSerial10 
COMS5 = \Device\VCP@ 


this will give you a list of active serial ports. Here the USB to UART Serial converter is on COM5. 


@ NOTE 


If you have multiple serial devices and can’t figure out which one is your UART to USB serial converter, try unplugging 


your cable, and running chgport again to see which COM port disappears. 


After entering the speed and port, click the "Open" button and you should see the UART output from the Raspberry Pi 
Pico in your Terminal window. 
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Chapter 10. Using other Integrated 
Development Environments 


Currently the recommended Integrated Development Environment (IDE) is Visual Studio Code, see Chapter 7. However 
other environments can be used with RP2040 and the Raspberry Pi Pico. 


10.1. Using Eclipse 


Eclipse is a multiplatform Integrated Development environment (IDE), available for x86 Linux, Windows and Mac. In 
addition, the latest version is now available for 64-bit ARM systems, and works well on the Raspberry Pi 4/400 range 
(4GB and up) running a 64-bit OS. The following instructions describe how to set up Eclipse on a Linux device for use 
with the Raspberry Pi Pico. Instructions for other systems will be broadly similar, although connections to the Raspberry 
Pi Pico will vary. See Section 9.2 and Section 9.1 for more details on non-Linux platforms. 


10.1.1. Setting up Eclipse for Pico on a Linux machine 


Prerequisites: 

* Device running a recent version of Linux with at least 4GB of RAM 

* 64-bit operating system. 

* CMake 3.11 or newer 
If using a Raspberry Pi, you should enable the standard UART by adding the following to config.txt 
enable uart-1 


You should also install OpenOCD and the SWD debug system. See Chapter 5 for instructions on how to do this. 


10.1.1.1. Installing Eclipse and Eclipse plugins 


Install the latest version of Eclipse with Embedded CDT using the standard instructions. If you are running on an ARM 
platform, you will need to install an AArch64 (64-bit ARM) version of Eclipse. All versions can be found on the Eclipse 
website. https://projects.eclipse.org/projects/iot.embed-cdt/downloads 


Download the correct file for your system, and extract it. You can then run it by going to the place where it was extracted 
and running the 'eclipse' executable. 


$ ./eclipse 


The Embedded CDT version of Eclipse includes the C/C++ development kit and the Embedded development kit, so has 
everything you need to develop for the Raspberry Pi Pico. 


10.1.1.2. Using pico-examples 
The standard build system for the Pico environment is CMake. However Eclipse does not use CMake as it has its own 


build system, so we need to convert the pico-examples CMake build to an Eclipse project. 
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e At the same level as the pico-examples folder, create a new folder, for example pico-examples-eclipse 
* Change directory to that folder 


e Set the path to the PICO SDK PATH 


$ export PICO. SDK PATH-«wherever» 


* On the command line enter: 


$ cmake -G"Eclipse CDT4 - Unix Makefiles" -DCMAKE. BUILD. TYPE-Debug ../pico-examples 


@ IMPORTANT 


The SDK builds binaries for the Raspberry Pi Pico by default. To build a binary for a different board, pass the 
-DPICO BOARD-«board» option to CMake, replacing the «board» placeholder with the name of the board you'd like to 


target. To build a binary for Pico W, pass -DPICO_BOARD=pico_w. To specify a Wi-Fi network and password that your Pico 
W should connect to, pass -DWIFI SSID-"Your Network" -DWIFI PASSWORD-"Your Password". 


This will create the Eclipse project files in our pico-examples-eclipse folder, using the source from the original CMake 
tree. 


You can now load your new project files into Eclipse using the Open project From File System option in the File menu. 


10.1.1.3. Building 


Right click on the project in the project explorer, and select Build. This will build all the examples. 


10.1.1.4. OpenOCD 


This example uses the OpenOCD system to communicate with the Raspberry Pi Pico. You will need to have provided the 
2-wire debug connections from the host device to the Raspberry Pi Pico prior to running the code. On a Raspberry Pi this 
can be done via GPIO connections, but on a laptop or desktop device, you will need to use extra hardware for this 
connection. One way is to use a second Raspberry Pi Pico running Picoprobe, which is described in Appendix A. More 
instructions on the debug connections can be found in Chapter 5. 


Once OpenOCD is installed and the correct connection made, Eclipse needs to be set up to talk to OpenOCD when 
programs are run. OpenOCD provides a GDB interface to Eclipse, and it is that interface that is used when debugging. 


To set up the OpenOCD system, select Preferences from the Window menu. 
Click on MCU arrow to expand the options and click on Global Open0CD path. 


For the executable, type in “openocd”. For the folder, select the location in the file system where you have cloned the 
Pico OpenOCD fork from github. 
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Figure 25. Setting the 
OCD executable name 


workspace - pico. examples-DebugGpico- examples. eclipse2/[Source directory|/spi/bme280. spi/bme280. spi.c- Eclipse Platform vax 


& || # || Œ 


and path in Eclipse. 


& Project Explorer 8 


, 
? B5 pico_examples-Debug@picc 


File Edit Source Refactor Navigate Search Project Run Window Help 
4# Debug 


type filter text 
» General 
+ C/C++ 


Help 
» Install/Update 


, rs uage Servers 


Global ARM Toolchains Paths 


Global Build Tools Path 


Workspace ARM Toolchains Paths 
Workspace Build Tools Path 
Workspace OpenOCD Path 

> Remote Development 

» Run/Debug 

> Team 

+ Terminal 


Preferences “vax 
Global OpenOCD Path Gro~ 8 


Configure the location where xPack OpenOCD is installed. TF 
stored within Eclipse. Unless redefined more specifically, the: 
all projects in all workspaces 


After installing OpenOCD updates, restart Eclipse for the defe 


evaluated and use the Restore Defaults button to configuret 
location. 


Executable: 


Folder 


gG-i*-0-WR-iB- 
Q m & + 
= o |g Out! $ Bul Doc = o 
BARSK? 
dig PB: inte 
dig P9: int6 t 
dig. H1 int t 
dig H3: uint8 t 
dig H6 :int8 t 
dig H2. int6 1 
dig H4: int6 t 
dig H5: int5 1 
compensate temp(int32 t) : int 
compensate pressure(int32. 1) 
® Compensate humidity(int32 :) 
o cs selecti): void 
© cs_deselect() void 
95 write register(uint8_t uint&. 1): v 
zP ° read, registers(uint8. t, uint8. 1*, 1 
= P read compensation parameters 
ep ° bme280 read raw(int32 t*, int3 


Em 
>> 4); 


D 
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mom 


E 


© eat 


Restore Defaults S gi F» 


3, 2020, 12:37:43 PM) 
Cancel Apply and Close 


(21) faultmask (/1): 0x00 
(22) control (/2): 0x00 

===== Cortex-M DWT registers 

target halted due to debug-request, current mode: Thread 
XPSR: 00100000 pc: 0x0000012a msp: 0x20041f00 


10.1.1.5. Creating a Run configuration 


In order to run or debug code in Eclipse you need to set up a Run Configuration. This sets up all the information needed 


to identify the code to run, any parameters, the debugger, source paths and SVD information. 


From the Eclipse Run menu, select Run Configurations. To create a debugger configuration, select GDB OpenOCD Debugging 
option, then select the New Configuration button. 


Figure 26. Creating a 


new Run/Debug 


& || # || Œ 


configuration in 


Eclipse. T Project Explor 


workspace - pico. examples-DebugGpico- examples eclipse2/[Source directory}/spi/bme280_spi/bme: 
File Edit Sout 


pm manage, and run configurations 


type filter text 
C/C++ Application 

[EIC/C+ Attach to Application 
[EIC/C++ Postmortem Debugger 
(EIC/C++ Remote Application 
Debug Adapter Launcher 
[EIGDB Hardware 


pico. examples Debug 
Launch Group 
® Launch Group (Deprecated) 


Filter matched 11 of 11 items 


pi.c- Eclipse Platform 


Debug Configurations SU 


Configure launch settings from this dialog 
- Press the 'New Configuration! button to create a configuration of the selected type. 


- Press the 'New Prototype' button to create a launch configuration prototype of the selected type. 


9 RU 


- Press the ‘Export’ button to export the selected configurations. 


fii 


- Press the ‘Duplicate’ button to copy the selected configuration. 


- Press the Delete button to remove the selected configuration. 


< 


- Press the Filter button to configure filtering options. 

- Edit or view an existing configuration by selecting it. 

T - Select launch configuration(s) and then select Link Prototype! menu item to link a prototype. 

W - Select launch configuration(s) and then select Unlink Prototype menu item to unlink a prototype 


- Select launch configuration(s) and then select Reset. type Values’ menu item to reset with prototype values 


Configure launch perspective settings from the Perspectives’ preference page. 


ressure(int32. 1) 
umidity(int32_1) 
id 

void 


(Oy =26 


® 


Close 


10.1.1.5.1. Setting up the application to run 


»mp(nt32 1) intz 


int8. t uint8. 1): v 


Because the pico-examples build creates lots of different application executables, you need to select which specific one 
is to be run or debugged. 


On the Main tab of the Run configuration page, use the Browse option to select the C/C++ applications you wish to run. 


The Eclipse build will have created the executables in sub folders of the Eclipse project folder. In our example case this 


is 


*/pico-examples-eclipse/«name of example folder>/<optional name of example subfolder»/executable.elf 


So for example, if we running the LED blink example, this can be found at: 
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Figure 27. Setting the 
executable to debug in 
Eclipse. 


/pico-examples-eclipse/blink/blink.elf 
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D, 12:37:43 PM) 
@ Duplicate Delete Cancel 


Vzz] vuntrut (zz]: xus 
===== Cortex-M DWI registers 

target halted due to debug-request, current mode: Thread 
xPSR: 0x61960008 pc: 0x0000012a nsp: 0x20041f00 

Info : dropped ‘gdb’ connection 


10.1.1.5.2. Setting up the debugger 


i 


We are using OpenOCD to talk to the Raspberry Pi Pico, so we need to set this up. 


Set openocd in the Executable box and Actual Executable box. We also need to set up OpenOCD to use the Pico specific 
configuration, so in the Config options sections add the following. Note you will need to change the path to point to the 


location where the Pico version of OpenOCD is installed. 


-f interface/raspberrypi-swd.cfg -f target/rp2040.cfg 


All other OpenOCD settings should be set to the default values. 


The actual debugger used is GDB. This talks to the OpenOCD debugger for the actual communications with the 


Raspberry Pi Pico, but provides a standard interface to the IDE. 


The particular version of GDB used is 'gdb-multiarch', so enter this in the Executable name and Actual Executable fields. 
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Figure 28. Setting up 
the Debugger and Create, manage, and run configurations 
OpenOCD in Eclipse. Q ! 


HBwgxX BY- Name: | pico. examples-Debug. pico. examples. eclipse Configuration 
type filter text | B Main {$ Debugger". > Startup | & Source| E Common)  SVD Path| 
Build Docker Image -OpenOCD Setup- — 
[£]C/C*- Application Start OpenOCD loca 
[£]C/C- Container Launcher Executable path: Browse... Variables... 
C/C++ Remote Application 
Ci C/C«- Unit Actual executablà | 
© Docker Compose ( Ge it use the global or workspace preferences pages or the project properties page) 
EIGDB Jumper Debugging GDB port: 3333 | 
~ [£]GDB OpenOCD Debugging Telnet port: 4444 
Bi pico pica 
Tcl port: 6666 
TEIGDB PyOCD Debugging Rules, à 
EIGDB QEMU Debugging Config options: Cf interface/raspberrypi-swd.cfg -f target/rp2040.cfg 
GDB SEGGER J-Link Debuggit 
* &Launch Group ~ Allocate console for OpenOCD ] Allocate console for the telnet connection 
Launch over Serial GDB Client Setup 
@ Run Docker Image Start GDB session 
Vioystemip Executable name// gdb-multiarch Browse. Variables... 
Actual executable, gdb-multiarch | 
Other options: 
Commands: set mem inaccessible-by-default off | 
Filter matched 17 of 19 items È Apply 


@ doe 


10.1.1.5.3. Setting up the SVD plugin 


SVD provides a mechanism to view and set peripheral registers on the Pico board. An SVD file provides register 
locations and descriptions, and the SVD plugin for Eclipse integrates that functionality in to the Eclipse IDE. The SVD 
plugin comes as part of the Embedded development plugins. 


Select the SVD path tab on the Launch configuration, and enter the location on the file system where the SVD file is 
located. This is usually found in the pico-sdk source tree. 


E.g. 


/pico-sdk/src/rp2040/hardware regs/rp2040.svd 


Figure 29. Setting the u 
SVD path in Eclipse. Create, manage, and run configurations Q 


= Name: | pico examples-Debug. pico examples eclipse Configuration 


Main ($+ Debugger | > Startup | Source [© Commo(( s. SVD Path’ 


Build Docker Image ‘SVD file (used by the peripheral registers viewer = 
C/C++ Application File path T: 
[EIC/C++ Container Launcher 
[EIC/C++ Remote Application 
CHC/C++ Unit 
© Docker Compose 
GDB Jumper Debugging 

~ [£]GDB OpenOCD Debugging 

Bi pico 


type filter text 


iome/pi/projects/pico. sdk/src/rp2040/hardware regs/rp2040 sve | Browse... Variables... 


[EIGDB PyOCD Debugging 
[EIGDB QEMU Debugging 
[GDB SEGGER J-Link Debuggit 
> &Launch Group 
Launch over Serial 
& Run Docker Image 
3$ SystemTap 


Revert Apply 


| Filter matched 17 of 19 items 


i 
i 
(9 Close Run 
i 
i 


10.1. Using Eclipse 54 


Getting started with Raspberry Pi Pico 
= 


Figure 30. The Eclipse 
debugger running, 
showing some of the 
debugging window 
available. 


10.1.1.5.4. Running the Debugger 


Once the Run configuration is complete and saved, you can launch immediately using the Run button at the bottom right 
of the dialog, or simply Apply the changes and Close the dialog. You can then run the application using the Run Menu Debug 
option. 


This will set Eclipse in to debug perspective, which will display a multitude of different debug and source code windows, 
along with the very useful Peripherals view which uses the SVD data to provide access to peripheral registers. From this 
point on this is a standard Eclipse debugging session. 


File Edit Source Refactor Navigate Search Project Run Window Help 


[& 4 | w] | % Debug E pico. examples2-Debug c Ge BO. Pues aD BEI Site Ore are THe egverorl m a 8 r3 
4e Debug Hi & Project Explorer E |ia bme2E0_spic tt = B fo- Variables |t Breakpoints LEN g = 
Ske we)? p " 
T pico examples2Debu configuration (CF MC PEINE i. uart (); wid uintB t 0520 (Hex) 
humidity iazet o 


+ Bibme280 spi elf 
is ze Printf("Hetlo, bne200* Reading raw date from registers via ST... W'); 


Thea 


wepessue int32 


Ln 


268442449 
536876512 


16 at 6.8 


ertemperature. 


slopenoed 
S gob-mutiarch 


E 
- 


Register block to control RTC 
Single-cycle IO block\n Provides core-local and inter-cor 


SCFG 
SYSINFO 
‘2 TBMAN 
TIMER 


040004000 
mnogonoo 
0x4006c000 
040054000 
T LARTO 040034000 
E 040038000 
T.USBCTRL Ri 0150110000 


Register block for various chip control signals 


Testbench manager. Allows the programmer to know wh 


Controls time and alarmsin time is @ 64 bit value indicat 


USB FS/LS controller device registers 


No details to disclav forthe current selection. 
te NHIJETSASENEN 


Monitors 


0x4003c000 
Dx4003c004 
0x4003c008 
Qx4003c00C 
maDoscoin 
oxa0030014 


‘0x00000000 
‘oxa0990000 
‘0x00000000 
000000003 
«0000000 
/0x00000000 


» mg SSPSR 
» BI SSPCPSR 
W SSPIMSC 


10.2. Using CLion 


CLion is a multiplatform Integrated Development environment (IDE) from JetBrains, available for Linux, Windows and 
Mac. This is a commercial IDE often the choice of professional developers (or those who love JetBrains IDEs) although 
there are free or reduce price licenses available. It will run on a Raspberry Pi, however the performance is not ideal, so it 
is expected you would be using CLion on your desktop or laptop. 


Whilst setting up projects, development and building are a breeze, setting up debug is still not very mainstream at the 
moment, so be warned. 


10.2.1. Setting up CLion 


If you are planning to use CLion we assume you either have it installed or can install it from https://www.jetbrains.com/ 
clion/ 


10.2.1.1. Setting up a project 


Here we are using pico-examples as the example project. 


To open the pico-examples project, select Open: from the File menu, and then navigate to and select the pico-examples 
directory you checked out, and press OK. 


Once open you'll see something like Figure 31. 
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Figure 31. A newly 
opened CLion pico- 
examples project. 


Figure 32. Configuring 
a CMake profile in 
CLion. 


pico-examples - README.md 


File Edit View Navigate Code Refactor Build Run Tools Git TeamCity Window Help 
plco-examples Add Configuration... = dtc v aO ma 
H E Project ~ tam README.md = 
E pico-examples / Xi s| H HT @ Ul g 
P. iii External Librarie E 
> “Scratches and Consoles z 
A PICO SDK Examples H 
2 
& s 
E z 
Getting started E 
E: Ej 
š 
H See the README in htips./cithub.com/raspberrynilpico-sdi for getting started information. 
E 
F Minimal Examples 
App Description Link to prebuilt UF2 
hello_world | The obligatory Hello World program for Pico (USB and Serial versions) — hiips;//pico.raspberrypi.or/uf2/hello world.uf2. 
blink Blink an LED on and off. hups://pico.raspberrypi.org/utz/blink.uf2 
ADC 
App Description. 
CMake 9 Debug $- 
5 [hone] arahan/ Vocat /share/2et&rains/Tootbox/apps/ CLion/ch-8/203.5981 .166/bin/cnake/linux/bin/cmake -DCHAKE BUILD TYPE-Debug -6 "CodeBlocks - Unix Makefiles" / 
| Stake Error at pico sdk inportcmaka:i (message): 
| PICO SDK location was not specified. Please set PICD_SDK_PATH or set 
% 79 | PICO SDK FETCH FROM SIT to on to fetch from git. 
sy = Call Stack (most recent call first): 
7 Æ| Cllakelists.txt:4 (include) 
i 
-- Configuring incomplete, errors occurred! 
E [Failed to reload] 

x H 
* Li 
© Problems P Gt Bi Terminal Teamcity | A CMake| = TODO Q Evert Log 

[s] LF UTF-8 4spaces P pre release "à @& i+ 


Notice at the bottom that CLion attempted to load the CMake project, but there was an error; namely that we hadn't 


specified PICO SDK PATH 


10.2.1.1.1. Configuring CMake Profiles 


Select Settings::: from the File menu, and then navigate to and select 'CMake' under Build, Execution, Deployment. 


You can set the environment variable PICO SDK PATH under Environment: as in Figure 32, or you can set it as 
-DPICO SDK PATH-xxx under CMake options:. These are just like the environment variables or command line args when 
calling cmake from the command line, so this is where you'd specify CMake settings such as PICO BOARD, 


PICO TOOLCHAIN PATH etc. 


Build, Execution, Deployment » CMake For current project 


AMARE E PENET Reload CMake project on editing CMakeLists.txt 


External changes always trigger project reload. For example, VCS update 


Reset 


Keymap 
> Editor Profiles 
Plugins Profile is a named set of build options. For example, create separate profiles For Debug and Release builds and switch between them 
> Version Control ATRIIS 
Build, Execution, Deployment +- Enable profile 
Toolchains A Debug Name: Debug 
= i : ~ | Corresponds to CMAKE BUILD TYPI 
compilation Database Build type: Debug Corresponds t E BUILD TYPE 
Custom Build Targets Toolchain: Use: Default v | Manage toolchains... 
Makefile TE 
; CMake options: -DCMAKE BUILD TYPE-Debug 
» Build Tools 
Use -DVAR_NAME=va ue to set variables, -G to specify a custom generator 
» Debugger All CMake options » 
Python Debugger 
Build directory: cmake-buil 
Python Interpreter 
Deployment Build options: 
> Console 9 the build, other arguments are 
Coverage Default options depend on the 
> Dynamic Analysis Tools 3 —— 
Embedded Development Environment: | PICO SDK PATH-/home/graham/dev/pico/pico-sdk 
" " Additional variabl CMake generation and build. The values are 
peregi added to system and hain variables. 
Swift 


Languages & Frameworks 


? ED o 


Apply 
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Figure 33. Configuring 
a second CMake 
Profile in CLion. 


Figure 34. Configuring 
a second CMake 
profile in CLion. 


@ IMPORTANT 


The SDK builds binaries for the Raspberry Pi Pico by default. To build a binary for a different board, pass the 
-DPICO BOARD-«board» option to CMake, replacing the «board» placeholder with the name of the board you'd like to 


target. To build a binary for Pico W, pass -DPICO BOARD-pico w. To specify a Wi-Fi network and password that your Pico 
W should connect to, pass -DWIFI SSID-"Your Network" -DWIFI PASSWORD-"Your Password". 


You can have as many CMake profiles as you like with different settings. You probably want to add a Release build by 
hitting the + button, and then filling in the PICO. SDK PATH again, or by hitting the copy button two to the right, and 


fixing the name and settings (see Figure 33) 


Build, Execution, Deployment » CMake 


> Appearance & Behavior 


External chang: 


Keymap 
> Editor 
Plugins 
> Version Control 
~ Build, Execution, Deployment 
Toolchains 


Compilation Database 


Profiles 


when needed. 
+- Ba 


A Debug 
A Release 


Name: 
Build type: 


Custom Build Targets 
Makefile 

> Build Tools 

» Debugger 
Python Debugger 
Python interpreter 

» Deployment 

> Console 


Toolchain: 


CMake options: 


Build directory: 


Build options: 


Coverage 
Dynamic Analysis Tools 
Embedded Development 
Required Plugins. 
Swift 


Environment: 


» Languages & Frameworks 


> 


Reload CMake project on editing CMakeLists.txt 


project rel 


For current project 


vad. For example, VCS update 


Profile is a named set of build options. For example, create separate profiles for Debug and Release builds and switch between them 


Enable profile 


Release 


Release v | Corresponds to CMAKE BUILD TYPE 


Use: Default * | Manage toolchains.. 
DCMAKE BUILD TYPE-Release 


Use -DVAR NAME-vaLlue to set variables, -G to specify a custom generator. 
All CMake options » 


cmake-build-release 


r"-' are passed to the build, other arguments are 
d line parameters. Default options depend on the 
ronment 


PICO_SDK_PATH=/home/graham/dev/pico/pico-sdk 


Reset 


Additic n and build. The values are 


adc 


al variable: 
system an. 


Make genera 


Cancel 


Apply 


After pressing OK, you'll see something like Figure 34. Note that there are two tabs for the two profiles (Debug and 
Release) at the bottom of the window. In this case Release is selected, and you can see that the CMake setup was 


pico examples - README.md o 
File Edit View Navigate Code Refactor Build Run Tools Git TeamCity Window Help 
pico-examples ^ |E adc console|Debug~| > 4 G Q & žno dcc v 7 Ha 
i = Project ~ Q = =| & — Æ READMEmd i 
& > t pico-examples HL ut @ =a 8 mF 
Be > ili External Libraries d 
w ° Scratches and Consoles PICO SDK Examples z 
E 
a s 
m : g 
Getting started E 
a H 
z See the README in hips;/cithub.com/raspberrypilpico-sdk for getting started information. 
E 
E Minimal Examples 
App Description Link to prebuilt UF2 
hello word | The obligatory Hello World program for Pico (USB and Serial versions) _https://pico.raspberrypi.org/ul2/hello_world.uf2 
blink Blink an LED on and off. hips://pico.raspberrypi.org/ufz/blink.uf2 
ADC 
App Description 
CMake: / Debug A Release $- 
s -- Found assembler: /usr/bin/arm-none-eabi-gcc 
Defaulting PICO target beard to pico since not specified 
Using board configuration from /home/graham/dev/pico/pico-sdk/src/boards/include/boards/pico.h 
-- Found Python3: /usr/bin/python3.8 (found version "3.8.5") found components: Interpreter 
TinyUSB available at /hone/graham/dev/pico/pico-sd«/Lib/tinyusb/src/portable/raspberrypi/rp2848; 
-- Found Doxygen: /usr/bin/doxygen (found version "1.8.17") found components: doxygen dot 
gi | ELF2UF2 witt need to be built 
PLOASH will need to be buat 
— Configuring done 
-- Generating done 
E] -- Build files have been written to: /home/sraham/dev/pico/pico-examples/cmake-build-release 
é [Finished] i 
* L3 
© Problems | Git Œ Terminal i Teamcity | A CMake = TODO Q Evert Log 
o 181 LF UTF-8 4spaces P pre release "à @ 4+ 


10.2.1.1.2. Running a build 


Now we can choose to build one or more targets. For example you can navigate to the drop down selector in the middle 
of the toolbar, and select or starting typing hello_usb; then press the tool icon to its left to build (see Figure 35). 
Alternatively you can do a full build of all targets or other types of build from the Build menu. 
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Figure 35. hello_usb 


successfully built File Edit View Navigate Code Refactor Build Run Tools Git Teamcity Window Help 
pico-sdk src rp2 common pico stdio 2" stdio.c ^ [S helo usb|Debug - | > SOQ # x Gté v2 GO 5|E 


pico examples - stdioc o 


© Project v © Iž $ — helousbc. 2 stdio.c 
pico-examples agysavir 

tl External Libraries cop ( Raspberry Pi (Tradi 

7o Scratches and Consoles 


ån Structure | Project 


include is: 


dif PICO STOIO UART 


Zenair 


F Pull Requests 


if PICO STDIO USB 
#include "pico/stdio usb.h* 
#endif 

28€ PICO_STOTO_SENTHOSTINS 
#ondif 

static stdio_driver_t »drivers; 


static stdio_driver_t #filter; 


sit PICO sTDDUT. MUTEX 
auto init mutex(print nutox); 


bool stdout_serialize beginO { 
int core-num = qet.core-nunQ ; 


Messages: Build 4- 
[160%] Building C object hello_world/usb/CMakeFiles/hello_usb.dir/home/graham/dev/pico/pico-sdk/lib/tinyusb/src/class/hid/hid_device.c.obj 

[1895] Building C object hello worló/usb/CHokeFiles/hello usb. dir/hone/arahan/dev/pizo/pizo-sdk/lib/tinyusb/src/class/nidi/midi device.c.obj 

T1885] Building C object hello-worla/usb/CHakeF Les/het lo. usb. dir/hone/arahan/dev/pico/pico-sdk/Aib/tinyust/src/ctass/net/net. device. c.obj 

[108%] Building C object netio worta/usb/CHakeF1tes/hetto. usb. dir/hone/grahan/dev/pco/p1ca-sdi/Atb/tinyusb/src/etass/usbtne/usbtne. device .c.obj 

[apex] suilding C object netio woric/usb/CMakeFites/netto. vsb. dir/nono/sranan/dev/pico/pco-sdi/1ib/tinyusb/src/ctass/nsc/nsc. device.c.obj 

[2884] Building C object nello worló/usb/CHakcF3Los/hoLlo. usb. dir/hono/sranan/dov/pizo/pizo-sdk/Lib/tinyusb/src/class/vandor/vendor. device .c.cbj 


fe ul 


[200%] Building C object heTLo_world/usb/CHakeFiLes/heLLo_vsb.dir/hone/grahan/dev/pico/pico-sdk/1ib/tinyusb/src/tusb.c.obj 

[180%] Building C object hello world/usb/CltakeF3Les/hello usb.dir/hone/aranan/dev/pico/pico-sdk/lib/tinyusb/ src/comon/ tusb. Fifo.c.obj 

[1005] Building C object nello world/usb/CltakeFiLes/hello vsb.dir/hone/arahan/dev/pico/pico-sdk/src/rp2 common/pico fix/rp2049 vsb device enumeration/rp2049 usb device enumeration. 
[108%] Linking CXX executable nello.usb.elf 

[imm] Built target nello usb 


= qt 


Build finished 


% Favorites. 


2 


@ Problems Git BiTeminal A CMake  Teamcity | Messages. = TODO. Q Event Log 
I: Build finished in 2 sec, 607 ms (moments ago) 27:1 LF UTF8 4spaces Cihello usb|Debug P pre release ù 4; i+ © 


Note that the drop down selector lets you choose both the target you want to build and a CMake profile to use (in this 
case one of Debug or Release) 


Another thing you'll notice Figure 35 shows is that in the bottom status bar, you can see hello usb and Debug again. 
These are showing you the target and CMake profile being used to control syntax highlighting etc. in the editor (This 
was auto selected when you chose hello usb before). You can visually see in the stdio.c file that has been opened by the 
user, that PICO. STDIO. USB is set, but PICO. STDIO. UART is not (which are part of the configuration of hello. usb). Build 
time per binary configuration of libraries is heavily used within the SDK, so this is a very nice feature. 


10.2.1.1.3. Build Artifacts 


The build artifacts are located under cmake-build-«profile» under the project root (see Figure 36). In this case this is the 
cmake-build-debug directory. 


The UF2 file can be copied onto an RP2040 device in BOOTSEL mode, or the ELF can be used for debugging. 


Figure 36. Locating 
the hello usb build 
artifacts 


pico examples - stdioc o 


File Edit View Navigate Code Refactor Build Run Tools Git TeamCity Window Help 


plco-examples  cmakebuild-debug hello_world usb i hello usb.uf? ^ [S helousb|Debug -] P & 6 GH & s dee 72 G5|t 
i Œ Project v © Z = 5 — Ahello_usbe dioc 
E ~ m pico-examples ~/dev/pico/pico-examples : ayaa ye 
. ee ita 
" blink 
E clocks 
f cmake s 
ao © Mn cmakebuild-debug ——— z 
F > Buadc ü 
H > Mbink if PICO STDIO UART 5 
H > m clocks 
Ac [A 
E > Ba cMakeriles 
> Ms divider 215 PICO_STOIO_use 
> mdma include "pico/stdio usb,h" 
> Welzuf? mait 
> Iflash 
> Im generated if PICO STDIO SEKIMOSTINS 
> Ingpio z ae 
~ In hello world tendir 
> Ba cMakeFiles 
> i serial static staio_oriver_t sanivers; 
v m usb static stdio_driver_t +filter; 


> Bs cmakefiles 
A cmake installcmake 

fh hello usb.bin 1/18/21, 

# hello usb dis 1/18 5 
f; hello usb.elF 1/19/21,9:13 PM, 57 
@ hello usb.elF.map 1/1/21,5:31 


#if PICO STDQUT MUTEX 
auto init mutex(print nutex); 


boot stdout 
int cane. 
vinti t 
if (mutex cor (Eprint_nutex, &ouner)) 4 
iF (owner == core num) { 
return false 


lalize.peginO £ 
get_core_nun(); 


Messages: Build *- 
T1895] Building C object hello-world/usb/CHakeF iLes/hetlo- usb. dir/hone/arahan/dev/pico/pico-sdk/Aib/tinyust/src/ctass/nsc/nsc device. c.ob 

[188%] Building C object netio worta/usb/CHakeF 1tes/het to. usb. di r/hone/grahan/dev/pco/pca-sdi/Atb/tinyusb/src/etass/vendor/vendor. device .c.obj 

[asax] Builaing C object netio.woric/usb/CMakeFites/netto. usb. dir/none/granan/dev/pico/pico-sdk/1ib/tinyusb/src/tusb.c.nbj 

[109%] Building C object nello world/usb/CHakeF3Les/heLlo. usb. dir/hone/orahan/dev/pico/pico-sdk/Lib/tinyusb/src/connon/ tusb. ifo. c.obj 

[286%] Building C object hello world/usb/CHakcF3los/hello. usb. dir/hono/srahan/dov/pico/pico-sdk/src/rp2. zonmon/pico. fix/rp2049. usb. device. onuneration/np2048.vsb. device. enumeration. 
[186%] Linking CXX executable hello usb.clf 

[100^] Built target nello usb 


Build finished 


E 


* 


@ Problems Hit Bi Terminal A CMake M Teamcity | Messages. = TODO Q Event Log 
E. Build finished in 2 sec, 607 ms (10 minutes ago) 27:1 LF UTF8 4spaces Cihello usb|Debug P pre release ù 5 i+ 
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10.3. Other Environments 


There are many development environments available, and we cannot describe all of them here, but you will be able to 
use many of them with the SDK. There are a number of things needed by your IDE that will make Raspberry Pi Pico 
support possible: 


* CMake integration 
* GDB support with remote options 
* SVD. Not essential but makes reading peripheral status much easier 


* Optional ARM embedded development plugin. These types of plugin often make support much easier. 


10.3.1. Using openocd-svd 


The openocd-svd tool is a Python-based GUI utility that gives you access peripheral registers of ARM MCUS via 
combination of OpenOCD and CMSIS-SVD. 


To install it you should first install the dependencies, 


$ sudo apt install python3-pyqt5 
$ pip3 install -U cmsis-svd 


before cloning the openocd-svd git repository. 


$ cd -/pico 
$ git clone https://github.com/esynr3z/openocd-svd.git 


Ensuring your Raspberry Pi 4 and Raspberry Pi Pico are correctly wired together, we can attach OpenOCD to the chip, via 
the sud and rp2040 configs. 


$ openocd -f interface/raspberrypi-swd.cfg -f target/rp2040.cfg 


Q WARNING 


If your flash has DORMANT mode code in it, or any code that stops the system clock, the debugger will fail to attach 


because the system clock is stopped. While this may present as a "bricked" board you can return to BOOTSEL mode 
using the button without problems. 


This OpenOCD terminal needs to be left open. So go ahead and open another terminal, in this one we'll attach a gdb 
instance to OpenOCD. 


Navigate to your project, and start gdb, 


$ cd ~/pico/test 
$ gdb-multiarch test.elf 


Connect GDB to OpenOCD, 
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(gdb) target remote localhost :3333 


and load it into flash, and start it running. 


(gdb) load 
(gdb) monitor reset init 
(gdb) continue 


With both openocd and gdb running, open a third window and start openocd-svd pointing it to the SVD file in the SDK. 


$ python3 openocd_svd.py /home/pi/pico/pico-sdk/src/rp2040/hardware. regs/rp2040.svd 


This will open the openocd-svd window. Now go to the File menu and click on "Connect OpenOCD" to connect via telnet to 
the running openocd instance. 


This will allow you to inspect the registers of the code running on your Raspberry Pi Pico, see Figure 37. 


Figure 37. OpenOCD 
SVD running and 
connected to the 


pico. bO.svd - openocd-svd 


File View Options Help 


Raspberry Pi Pico. 
No description k 
Register Value : 
* UARTDR 0x00000000 R W 
* UARTRSR 0x00000000 RW 
+ UARTFR 0x00000197 RW 
+ UARTILPR 0x00000000 R W 
* UARTIBRD 0x00000043 Rw 
* UARTFBRD 0x00000034 R W 
* UARTLCR_H 0x00000070 RW 
* UARTCR 0x00000301 RW 
* UARTIFLS 0x00000012 RW 
# UARTIMSC 0x00000000 R W 
* UARTRIS 0x00000000 RW 
+ UARTMIS 0x00000000 R W 
+ UARTICR 0x00000000 RW 
+ UARTDMACR 0x00000003 RW 
+ UARTPERIPHIDO 0x00000011 RW 
+| UARTPERIPHIDT 0x00000010 R W 
* UARTPERIPHID2 0x00000034 R W 
+ UARTPERIPHID3 0x00000000 R W 
* UARTPCELLIDO Ox0000000d RW 
+ UARTPCELLID1 Ox000000fO RW, 
UARTO & | UART1 


Read UARTO.UARTPCELLIDS @ Ox4OCConnected: rp2bO.corel | running | OXO00000EE 
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Figure 38. Wiring 
between Pico A (left) 
and Pico B (right) with 
Pico A acting as a 
debug probe. At least 
the ground and the 
two SWD wires must 
be connected, for one 
Pico to be able to 
reprogram and debug 
another. This diagram 
also shows how the 
UART serial port can 
be connected, so that 
you can see the UART 
serial output of the 
Pico-under-test, and 
how the power supply 
can be bridged across, 
so that both boards 
are powered by one 
USB cable. More in 
Picoprobe Wiring. 


Appendix A: Using Picoprobe 


One Raspberry Pi Pico can be used to reprogram and debug another, using the picoprobe firmware, which transforms a 
Pico into a USB > SWD and UART bridge. This makes it easy to use a Raspberry Pi Pico on non-Raspberry Pi platforms 
such as Windows, Mac, and Linux computers where you don't have GPIOs to connect directly to UART or SWD, but you 
do have a USB port. 
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Raspberry Pi Debug Probe 


If you don't want to use a second Raspberry Pi Pico for debugging we now also produce the Raspberry 
Pi Debug Probe. The Raspberry Pi Debug Probe provides: Serial Wire Debug (SWD), and a generic USB- 
to-Serial bridge. 


While it has been designed with Raspberry Pi Pico, and other RP2040-based targets, in mind, the 
Raspberry Pi Debug Probe can be used to debug any Arm-based microcontroller that provides an SWD 
port with 3V3 I/O. Full documentation and more information about the Debug Probe can be found online 
on the documentation site. 


Build OpenOCD 


For picoprobe to work, you need to build OpenOCD from the Raspberry Pi GitHub repository. 


@ NOTE 


Previous picoprobe firmware versions required a custom OpenOCD protocol driver, this is no longer necessary. 


Linux 


$ cd ~/pico 

$ sudo apt install automake autoconf build-essential texinfo libtool libftdi-dev libusb-1.0-0- 
dev 

$ git clone https://github.com/raspberrypi/openocd.git --branch rp2040-v0.12.0 --depth-1 

$ cd openocd 

$ ./bootstrap 

$ ./configure (D 

$ make -j4 


Build OpenOCD 
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$ sudo make install 


1. If you are building on a Raspberry Pi you can also pass --enable-sysfsgpio --enable-bcm2835gpio to allow bitbanging 
SWD via the GPIO pins. 


@ NOTE 


Ubuntu and Debian users might additionally need to also install pkg-config. 


Windows 


To make building OpenOCD as easy as possible, we will use MSYS2. To quote their website: "MSYS2 is a collection of 
tools and libraries providing you with an easy-to-use environment for building, installing and running native Windows 
software." 


Download and run the installer from https://www.msys2.org/. 


Start by updating the package database and core system packages with: 


$ pacman -Syu 


If MSYS2 closes, start it again (making sure you select the 64-bit version) and run 


$ pacman -Su 


to finish the update. 


Install required dependencies: 


$ pacman -S mingw-w64-x86_64-toolchain git make libtool pkg-config autoconf automake texinfo 
mingw-w64-x86. 64-libusb 


Pick all when installing the mingw-w64-x86. 64 toolchain by pressing enter. 
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Close MSYS2 and reopen the 64-bit version to make sure the environment picks up GCC. 


$ git clone https://github.com/raspberrypi/openocd.git --branch rp2040-v0.12.0 --depth-1 
$ cd openocd 

$ ./bootstrap 

$ ./configure --disable-werror © 

$ make -j4 


1. Unfortunately disable-werror is needed because not everything compiles cleanly on Windows 


Finally run OpenOCD to check it has built correctly. Expect it to error out because no configuration options have been 
passed. 


$ src/openocd.exe 
Open On-Chip Debugger 0.10.0*dev-gc231502-dirty (2020-10-14-14:37) 
Licensed under GNU GPL v2 
For bug reports, read 
http://openocd.org/doc/doxygen/bugs.html 
embedded:startup.tcl:56: Error: Can't find openocd.cfg 
in procedure ‘script’ 
at file "“embedded:startup.tcl", line 56 
Info : Listening on port 6666 for tcl connections 
Info : Listening on port 4444 for telnet connections 
Error: Debug Adapter has to be specified, see "interface" command 
embedded:startup.tcl:56: Error: 
in procedure 'script' 
at file 'embedded:startup.tcl", line 56 


Mac 


Install brew if needed 


$ /bin/bash -c "S(curl -fsSL 
https://raw.githubusercontent.com/Homebrew/install/master/install.sh)" 
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Install dependencies 
$ brew install libtool automake libusb wget pkg-config gcc texinfo © 
1. The version of texinfo shipped with OSX is below the version required to build OpenOCD docs 


$ cd ~/pico 

$ git clone https://github.com/raspberrypi/openocd.git --branch rp2040-v0.12.0 --depth-1 
$ cd openocd 

$ export PATH="/usr/local/opt/texinfo/bin:SPATH" © 

$ ./bootstrap 

$ ./configure --disable-werror @ 

$ make -j4 


1. Put newer version of texinfo on the path 
2. Unfortunately disable-werror is needed because not everything compiles cleanly on OSX 


Check OpenOCD runs. Expect it to error out because no configuration options have been passed. 


$ src/openocd 
Open On-Chip Debugger @.1@.0+dev-gc2315@2-dirty (2020-10-15-07:48) 
Licensed under GNU GPL v2 
For bug reports, read 
http://openocd.org/doc/doxygen/bugs.html 
embedded:startup.tcl:56: Error: Can't find openocd.cfg 
in procedure ‘script’ 
at file "embedded:startup.tcl", line 56 
Info : Listening on port 6666 for tcl connections 
Info : Listening on port 4444 for telnet connections 
Error: Debug Adapter has to be specified, see "interface" command 
embedded:startup.tcl:56: Error: 
in procedure 'script' 
at file "embedded:startup.tcl", line 56 


Build and flash picoprobe 


Picoprobe UF2 Download 


A UF2 binary of picoprobe can be downloaded from the Software Utilities section of the Raspberry Pi 
Pico documentation page. Click on the Raspberry Pi Pico section, scroll down to Software Utilities, and 
download the UF2 under "Debugging using another Raspberry Pi Pico". 


These build instructions assume you are running on Linux, and have installed the SDK. 


cd ~/pico 

git clone https://github.com/raspberrypi/picoprobe.git 
cd picoprobe 

git submodule update --init 

mkdir build 

$ cd build 

$ export PICO. SDK PATH-../../pico-sdk 
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Figure 39. Wiring 
between Pico A (left) 
and Pico B (right) 
configuring Pico A as 
a debugger. Note that 
if Pico B is a USB Host 
then you'd want to 
hook VBUS up to VBUS 
so it can provide 5V 
instead of VSYS to 
VSYS. 


$ cmake .. 
$ make -j4 
@ IMPORTANT 


The SDK builds binaries for the Raspberry Pi Pico by default. To build a binary for a different board, pass the 
-DPICO BOARD-«board» option to CMake, replacing the «board» placeholder with the name of the board you'd like to 


target. To build a binary for Pico W, pass -DPICO_BOARD=pico_w. To specify a Wi-Fi network and password that your Pico 
W should connect to, pass -DWIFI SSID-"Your Network" -DWIFI PASSWORD-"Your Password". 


Boot the Raspberry Pi Pico you would like to act as a debugger with the BOOTSEL button pressed and drag on 
picoprobe.uf2. 


Picoprobe Wiring 
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The wiring loom between the two Pico boards is shown in Figure 39. 


Pico A GND -> Pico B GND 

Pico A GP2 -» Pico B SWCLK 

Pico A GP3 -» Pico B SWDIO 

Pico A GP4/UART1 TX -> Pico B GP1/UART@ RX 
Pico A GP5/UART1 RX -> Pico B GP@/UART®@ TX 


The minimum set of connections for loading and running code via OpenOCD is GND, SWCLK and SWDIO. Connecting up 
the UART wires will also let you communicate with the right-hand Pico's UART serial port through the left-hand Pico's 
USB connection. You can also use just the UART wires to talk to any other UART serial device, like the boot console on a 
Raspberry Pi. 


Optionally, to power Pico A from Pico B you should also wire, 
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Pico A VSYS -» Pico B VSYS 


@ IMPORTANT 


If Pico B is a USB Host then you must connect VBUS to VBUS, not VSYS to VSYS, so that Pico B can provide 5V on its 


USB connector. If Pico B is using USB in device mode, or not using its USB at all, this is not necessary. 


Picoprobe Interfaces 


The Picoprobe device is a composite device that has two USB interfaces: 
1. Aclass-compliant CDC UART (serial port), which means it works on Windows out of the box 


2. A vendor-specific interface for SWD probe data conforming to CMSIS-DAP v2. 


@ NOTE 


Previous picoprobe firmware versions required manual installation of libusb-win32 for the vendor-specific interface. 


This is no longer necessary, as WinUSB is automatically assigned to the debug interface. 


Using Picoprobe's UART 
Linux 


$ sudo minicom -D /dev/ttyACMO -b 115200 


Windows 


Download and install PUTTY https://www.chiark.greenend.org.uk/~sgtatham/putty/latest.html 


Open Device Manager and locate Picoprobe's COM port number. In this example it is COM7. 
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ih Device Manager 


File Action View Help 
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Open PuTTY. Select Serial under connection type. Then type the name of your COM port along with 115200 as the 


speed. 
R PuTTY Configuration ? x 
Category: 

| _~ Logging the destination you want to connect t 

È- Teminal arte you o 

P ono oO 
B- Window Cae or" (QRlogn OSSH @ Seral 
i foras 3 Load, save or delete a stored session 


Select Open to start the serial console. You are now ready to run your application! 
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COM7 - PuTTY = x 
P 


Mac 


We can install minicom using Homebrew, 


$ brew install minicom 
$ minicom -D /dev/tty.usbmodem1234561 -b 115200 


Using Picoprobe with OpenOCD 


Same for all platforms, 
$ src/openocd -f interface/cmsis-dap.cfg -c "adapter speed 5000" -f target/rp2040.cfg -s tcl 
Connect GDB as you usually would with 


target remote localhost:3333 
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Appendix B: Using Picotool 


It is possible to embed information into a Raspberry Pi Pico binary, which can be retrieved using a command line utility 
called picotool. 


Getting picotool 


The picotool utility is available in its own repository. You will need to clone and build it if you haven't ran the pico-setup 
Script. 


$ git clone https://github.com/raspberrypi/picotool.git --branch master 
$ cd picotool 


You will also need to install Libusb if it is not already installed, 


$ sudo apt install libusb-1.0-0-dev 


@ NOTE 


If you are building picotool on macOS you can install Libusb using Homebrew, 


$ brew install libusb pkg-config 


While if you are building on Microsoft Windows you can download and install a Windows binary of libusb directly 
from the libusb.info site. 


Building picotool 


Building picotool can be done as follows, 


mkdir build 

cd build 

export PICO. SDK. PATH--/pico/pico-sdk 
cmake ../ 

make 


9» 0» 0» 0» WD 


——————————— 
Getting picotool 69 


Getting started with Raspberry Pi Pico 


@ IMPORTANT 


The SDK builds binaries for the Raspberry Pi Pico by default. To build a binary for a different board, pass the 
-DPICO BOARD-«board» option to CMake, replacing the «board» placeholder with the name of the board you'd like to 


target. To build a binary for Pico W, pass -DPICO BOARD-pico w. To specify a Wi-Fi network and password that your Pico 
W should connect to, pass -DWIFI SSID-"Your Network" -DWIFI PASSWORD-"Your Password". 


this will generate a picotool command-line binary in the build/picotool directory. 


@ NOTE 


If you are building on Microsoft Windows you should invoke CMake as follows, 


C:\Users\pico\picotool> mkdir build 


C:\Users\pico\picotool> cd build 
C:\Users\pico\picotool\build> cmake .. -G "NMake Makefiles" 
C:\Users\pico\picotool\build> nmake 


Using picotool 


The picotool binary includes a command-line help function, 


$ picotool help 
PICOTOOL : 
Tool for interacting with a RP2040 device in BOOTSEL mode, or with a RP2040 binary 


SYNOPSIS: 

picotool info [-b] [-p] [-d] [-1] [-a] [--bus <bus>] [--address <addr>] [-f] [-F] 

picotool info [-b] [-p] [-d] [-1] [-a] «filename» [-t <type>] 

picotool load [-n] [-N] [-v] [-x] «filename» [-t <type>] [-o <offset>] [--bus <bus>] 
[--address <addr>] [-f] [-F] 

picotool save [-p] [--bus <bus>] [--address <addr>] [-f] [-F] «filename» [-t <type>] 

picotool save -a [--bus <bus>] [--address <addr>] [-f] [-F] «filename» [-t <type>] 

picotool save -r «from» «to» [--bus <bus>] [--address <addr>] [-f] [-F] «filename» [-t 
<type>] 

picotool verify [--bus <bus>] [--address <addr>] [-f] [-F] <filename> [-t <type>] [-r 
<from> <to>] [-o <offset>] 

picotool reboot [-a] [-u] [--bus <bus>] [--address <addr>] [-f] [-F] 

picotool version [-s] 

picotool help [<cmd>] 


COMMANDS : 

info Display information from the target device(s) or file. 
Without any arguments, this will display basic information for all connected 
RP2040 devices in BOOTSEL mode 

load Load the program / memory range stored in a file onto the device. 

save Save the program / memory stored in flash on the device to a file. 

verify Check that the device contents match those in the file. 

reboot Reboot the device 


version Display picotool version 
help Show general help or help for a specific command 


Use "picotool help <cmd>" for more info 
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@ NOTE 


The majority of commands require an RP2040 device in BOOTSEL mode to be connected. 


@ IMPORTANT 


If you get an error message No accessible RP2040 devices in BOOTSEL mode were found. accompanied with a note similar 
to Device at bus 1, address 7 appears to be a RP2040 device in BOOTSEL mode, but picotool was unable to connect 
indicating that there was a Raspberry Pi Pico connected then you can run picotool using sudo, e.g. 


$ sudo picotool info -a 


If you get this message on Windows you will need to install a driver. 


Download and run Zadig, select Picotool from the dropdown box and select libusb-win32 as the driver, and click on 
the "Install Driver" button. 


As of version 1.1 of picotool it is also possible to interact with RP2040 devices that are not in BOOTSEL mode, but are 
using USB stdio support from the SDK by using the -f argument of picotool. 


Display information 


So there is now Binary Information support in the SDK which allows for easily storing compact information that picotool 
can find (See Binary Information below). The info command is for reading this information. 


The information can be either read from one or more connected RP2040 devices in BOOTSEL mode, or from a file. This 
file can be an ELF, a UF2 or a BIN file. 


$ picotool help info 

INFO: 
Display information from the target device(s) or file. 
Without any arguments, this will display basic information for all connected RP2040 devices 
in BOOTSEL mode 


SYNOPSIS: 
picotool info [-b] [-p] [-d] [-1] [-a] [--bus <bus>] [--address <addr>] [-f] [-F] 
picotool info [-b] [-p] [-d] [-1] [-a] «filename» [-t <type>] 


OPTIONS: 
Information to display 
-b, --basic 
Include basic information. This is the default 


=), pus 
Include pin information 
-d, --device 


Include device information 


-l, --build 
Include build attributes 
-a, --all 


Include all information 


TARGET SELECTION: 
To target one or more connected RP2040 device(s) in BOOTSEL mode (the default) 
--bus «bus» 
Filter devices by USB bus number 
--address <addr> 
Filter devices by USB device address 
-f, --force 
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Force a device not in BOOTSEL mode but running compatible code to reset so the 
command can be executed. After executing the command (unless the command itself is 
a 'reboot') the device will be rebooted back to application mode 

-F, --force-no-reboot 
Force a device not in BOOTSEL mode but running compatible code to reset so the 
command can be executed. After executing the command (unless the command itself is 
a 'reboot') the device will be left connected and accessible to picotool, but 
without the RPI-RP2 drive mounted 

To target a file 

«filename» 
The file name 

-t <type> 
Specify file type (uf2 | elf | bin) explicitly, ignoring file extension 


For example connect your Raspberry Pi Pico to your computer as mass storage mode, by pressing and holding the 
BOOTSEL button before plugging it into the USB. Then open up a Terminal window and type, 


$ sudo picotool info 
Program Information 

name: hello. world 
features: stdout to UART 


or, 


$ sudo picotool info -a 
Program Information 


name: hello. world 
features: stdout to UART 
binary start:  0x10000000 
binary end: 0x1000606c 


Fixed Pin Information 
20: UART1 TX 
21: VARTI RX 


Build Information 
build date: Dec 31 2020 
build attributes: Debug build 


Device Information 
flash size: 2048K 
ROM version: 2 


for more information. Alternatively you can just get information on the pins used as follows, 


$ sudo picotool info -bp 
Program Information 
name: hello. world 
features: stdout to UART 


Fixed Pin Information 


20: UART1 TX 
21: UART1 RX 


The tool can also be used on binaries still on your local filesystem, 
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$ picotool info -a lcd. 1602 i2c.uf2 
File lcd. 1602 i2c.uf2: 


Program Information 


name: lcd. 1602. i2c 

web site: https://github.com/raspberrypi/pico-examples/tree/HEAD/i2c/lcd. 1602 i2c 
binary start:  0x10000000 

binary end: 0x10003c1c 


Fixed Pin Information 
4: I2C0 SDA 
Be X SCIE 


Build Information 
build date: Dec 31 2020 


Save the program 


Save allows you to save a range of memory or a program or the whole of flash from the device to a BIN file or a UF2 file. 


$ picotool help save 
SAVE: 
Save the program / memory stored in flash on the device to a file. 


SYNOPSIS: 
picotool save [-p] [--bus <bus>] [--address <addr>] [-f] [-F] <filename> [-t <type>] 
picotool save -a [--bus <bus>] [--address <addr>] [-f] [-F] <filename> [-t <type>] 
picotool save -r <from> <to> [--bus <bus>] [--address <addr>] [-f] [-F] <filename> [-t 


<type>] 
OPTIONS: 
Selection of data to save 
-p, --program 
Save the installed program only. This is the default 
-a, --all 
Save all of flash memory 
-r, --range 
Save a range of memory. Note that UF2s always store complete 256 byte-aligned 
blocks of 256 bytes, and the range is expanded accordingly 
«from» 
The lower address bound in hex 
«to» 


The upper address bound in hex 
Source device selection 
--bus «bus» 
Filter devices by USB bus number 
--address <addr> 
Filter devices by USB device address 
-f, --force 
Force a device not in BOOTSEL mode but running compatible code to reset so the 
command can be executed. After executing the command (unless the command itself is 
a 'reboot') the device will be rebooted back to application mode 
-F, --force-no-reboot 
Force a device not in BOOTSEL mode but running compatible code to reset so the 
command can be executed. After executing the command (unless the command itself is 
a 'reboot') the device will be left connected and accessible to picotool, but 
without the RPI-RP2 drive mounted 
File to save to 
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«filename» 
The file name 
=t <type> 
Specify file type (uf2 | elf | bin) explicitly, ignoring file extension 


For example, 


$ sudo picotool info 

Program Information 

name: Ted 1602. i2c 

web site: https://github.com/raspberrypi/pico-examples/tree/HEAD/i2c/lcd. 1602 i2c 
$ picotool save spoon.uf2 

Saving file: [|==s=======s===================]) 100% 

Wrote 51200 bytes to spoon.uf2 

$ picotool info spoon.uf2 

File spoon.uf2: 

Program Information 

name: lcd. 1602. i2c 

web site: https://github.com/raspberrypi/pico-examples/tree/HEAD/i2c/lcd. 1602 i2c 


Binary Information 


Binary information is machine-locatable and generally machine-consumable. | say generally because anyone can 
include any information, and we can tell it from ours, but it is up to them whether they make their data self-describing. 


Basic information 


This information is really handy when you pick up a Pico and don't know what is on it! 
Basic information includes 


* program name 


program description 


* program version string 


program build date 


program url 


program end address 


program features, this is a list built from individual strings in the binary, that can be displayed (e.g. we will have one 
for UART stdio and one for USB stdio) in the SDK 


build attributes, this is a similar list of strings, for things pertaining to the binary itself (e.g. Debug Build) 


Pins 


This is certainly handy when you have an executable called hello serial.elf but you forgot what RP2040-based board it 
was built for, as different boards may have different pins broken out. 


Static (fixed) pin assignments can be recorded in the binary in very compact form: 
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$ picotool info --pins sprite demo.elf 
File sprite. demo.elf: 


Fixed Pin Information 
90-4: Red 0-4 

6-110); Green 0-4 
11-15: Blue @-4 


16: HSync 

17/3 VSync 

18: Display Enable 
19: Pixel Clock 
20: UART1 TX 

ge UART1 RX 


Including Binary information 


Binary information is declared in the program by macros; for the previous example: 


$ picotool info --pins sprite demo.elf 
File sprite demo.elf: 


Fixed Pin Information 
8-4: Red 0-4 

6-10: Green 0-4 
11-15: Blue 0-4 


NOR HSync 

Ws VSync 

TSE Display Enable 
19: Pixel Clock 
20: UART1 TX 

2d UART1 RX 


There is one line in the setup_default_uart function: 


bi_decl_if_func_used(bi_2pins_with_func(PICO_DEFAULT_UART_RX_PIN, PICO_DEFAULT_UART_TX_PIN, 
GPIO_FUNC_UART) ) ; 


The two pin numbers, and the function UART are stored, then decoded to their actual function names (UART1 TX etc) by 
picotool. The bi decl if func used makes sure the binary information is only included if the containing function is called. 


Equally, the video code contains a few lines like this: 


bi. decl if. func used(bi. pin mask. with, name(0x1f << (PICO. SCANVIDEO. COLOR. PIN.BASE + 
PICO. SCANVIDEO. DPI. PIXEL. RSHIFT), "Red 0-4")); 


Details 


Things are designed to waste as little space as possible, but you can turn everything off with preprocessor var 
PICO NO BINARY INFO-1. Additionally any SDK code that inserts binary info can be separately excluded by its own 
preprocessor var. 
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You need, 


#include "pico/binary info.h" 


There are a bunch of bi macros in the headers 


#define bi binary end(end) 

#define bi program. .name(name) 

#define bi program description(description) 

#define bi program version string(version string) 

#define bi program build date string(date string) 

#define bi program url(url) 

#define bi program feature(feature) 

#define bi program build attribute(attr) 

#define bi 1pin with func(p0, func) 

#define bi 2pins with func(p0, p1, func) 

#define bi 3pins with func(p0, p1, p2, func) 

#define bi 4pins with func(p0, p1, p2, p3, func) 

#define bi 5pins with func(p0, p1, p2, p3, p4, func) 

#define bi pin range with func(plo, phi, func) 

#define bi pin mask with. name(pmask, label) 

#define bi pin mask with .names(pmask, label) 

#define bi 1pin with name(p0, name) 

#define bi 2pins with .names(p0, name@, p1, name!) 

#define bi 3pins with names(p0, name0, p1, name1, p2, name2) 
#define bi 4pins with names(p0, name@, p1, name1, p2, name2, p3, name3) 


which make use of underlying macros, e.g. 


#define bi program url(url) bi string(BINARY. INFO. TAG RASPBERRY PI, BINARY INFO. ID RP PROGRAM URL, 
url) 


You then either use bi decl(bi blah(:*:)) for unconditional inclusion of the binary info blah, or 
bi decl if func used(bi blah(:*:)) for binary information that may be stripped if the enclosing function is not included in 
the binary by the linker (think --gc-sections). 


For example, 


#include <stdio.h> 

#include "pico/stdlib.h" 
#include "hardware/gpio.h" 
#include "pico/binary info.h" 


const uint LED. PIN = 25; 
int main() ( 


bi decl(bi. program description("This is a test binary.")); 
bi. decl(bi. 1pin with. name(LED. PIN, "On-board LED")); 


setup. default uart(); 
gpio.set. function(LED. PIN, GPIO. FUNC. PROC) ; 
gpio.set dir(LED. PIN, GPIO. OUT); 
while (1) ( 
gpio. put(LED. PIN, 0); 
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18 sleep. ms(250); 

19 gpio.put(LED. PIN, 1); 
20 puts("Hello World in"); 
21 sleep ms(1000); 

22 } 

28 } 


when queried with picotool, 


$ sudo picotool info -a test.uf2 
File test.uf2: 


Program Information 


name: test 

description: This is a test binary. 
features: stdout to UART 

binary start:  0x10000000 

binary end: 0x100031f8 


Fixed Pin Information 
0: UARTO TX 

Abe UART@ RX 

25: On-board LED 


Build Information 


build date: Jan 4 2021 


shows our information strings in the output. 


Setting common fields from CMake 


You can also set fields directly from your project's CMake file, e.g., 


pico.set program name(foo "not foo") (D 

pico.set program description(foo "this is a foo") 
pico.set. program. version. string(foo "0.00001a") 
pico.set program url(foo "www.plinth.com/foo") 


1. The name "foo" would be the default. 


@ NOTE 


All of these are passed as command line arguments to the compilation, so if you plan to use quotes, newlines etc. 


you may have better luck defining it using bi decl in the code. 
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Table 1. 
Documentation 


Release Date 


Description 


release history 1.0 21 Jan 2021 


1.1 26 Jan 2021 


* |nitial release 


* Minor corrections 

* Extra information about using DMA with ADC 

e Clarified MO+ and SIO CPUID registers 

* Added more discussion of Timers 

e Update Windows and macOS build instructions 


* Renamed books and optimised size of output PDFs 


12 01 Feb 2021 


* Minor corrections 

* Small improvements to PIO documentation 

* Added missing TIMER2 and TIMER3 registers to DMA 
* Explained how to get MicroPython REPL on UART 


* To accompany the V1.0.1 release of the C SDK 


1.3 23 Feb 2021 


* Minor corrections 

* Changed font 

* Additional documentation on sink/source limits for RP2040 
* Major improvements to SWD documentation 

* Updated MicroPython build instructions 

* MicroPython UART example code 

* Updated Thonny instructions 

* Updated Project Generator instructions 

* Added a FAQ document 


* Added errata E7, E8 and E9 


1.3.1 05 Mar 2021 


* Minor corrections 
* To accompany the V1.1.0 release of the C SDK 
* Improved MicroPython UART example 


* Improved Pinout diagram 


1.4 07 Apr 2021 


* Minor corrections 
* Added errata E10 
* Note about how to update the C SDK from Github 


* To accompany the V1.1.2 release of the C SDK 
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Release Date Description 


1.4.1 13 Apr 2021 * Minor corrections 


* Clarified that all source code in the documentation is under the 
3-Clause BSD license. 


1.5 07 Jun 2021 * Minor updates and corrections 
* Updated FAQ 
* Added SDK release history 


* To accompany the V1.2.0 release of the C SDK 


1.6 23 Jun 2021 * Minor updates and corrections 
* ADC information updated 


* Added errata E11 


1.6.1 30 Sep 2021 * Minor updates and corrections 
e Information about B2 release 


* Updated errata for B2 release 


1.7 03 Nov 2021 * Minor updates and corrections 

* Fixed some register access types and descriptions 
* Added core 1 launch sequence info 

* Described SDK "panic" handling 

* Updated picotool documentation 


* Additional examples added to Appendix A: App Notes appendix 
in the Raspberry Pi Pico C/C++ SDK book 


* To accompany the V1.3.0 release of the C SDK 


1.7.1 04 Nov 2021 * Minor updates and corrections 
* Better documentation of USB double buffering 
* Picoprobe branch changes 


* Updated links to documentation 


1.8 17 Jun 2022 * Minor updates and corrections 


* Updated setup instructions for Windows in Getting started with 
Raspberry Pi Pico 


* Additional explanation of SDK configuration 


* RP2040 now qualified to -40*C, minimum operating temperature 
changed from -20*C to -40*C 


* Increased PLL min VCO from 400MHz to 750MHz for improved 
stability across operating conditions 


* Added reflow-soldering temperature profile 
* Added errata E12, E13 and E14 


* To accompany the V1.3.1 release of the C SDK 
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Release Date Description 


1.9 30 Jun 2022 * Minor updates and corrections 


* Update to VGA board hardware description for launch of 
Raspberry Pi Pico W 


* To accompany the V1.4.0 release of the C SDK 


Pico and Pico W databooks combined into a unified release history 


2.0 01 Dec 2022 * Minor updates and corrections 
* Added RP2040 availability information 
* Added RP2040 storage conditions and thermal characteristics 


* Replace SDK library documentation with links to the online 
version 


* Updated Picoprobe build and usage instructions 


2.1 03 Mar 2023 * Alarge number of minor updates and corrections 

* SMT footprint of Pico W corrected 

* Updated for the 1.5.0 release of the Raspberry Pi Pico C SDK 
* Added errata E15 

* Added documentation around the new Pico Windows Installer 


* Added documentation around the Pico-W-Go extension for 
Python development 


* Added a wireless networking example to the Python 
documentation 


* Added package marking specifications 
* Added RP2040 baseline power consumption figures 


* Added antenna keep out diagram to Pico W datasheet 


2:2 14 Jun 2023 * Minor updates and corrections 
* Updated for the 1.5.1 release of the Raspberry Pi Pico C SDK 


* Documentation around Bluetooth support for Pico W 


2:3 02 Feb 2024 * Numerous minor updates and corrections 
* Update ROSC register information 


* Updated getting started documentation for MS Windows and 
Apple macOS 


* Updates arising from the release of Raspberry Pi 5 


* Reintroduced updated SDK library documentation (was 
withdrawn in 2.0 due to XML conflicts) 


* Updated to include the new recommended part number for 
crystals used with RP2040 


* Added new paste stencil information for Pico and Pico W 


* Other updates to supporting documentation 
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The latest release can be found at https://datasheets.raspberrypi.com/pico/getting-started-with-pico.pdf. 
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Raspberry Pi is a trademark of Raspberry Pi Ltd 


Raspberry Pi Ltd 


